企业官网建设流程全解析

如果你正在用 Claude Code 写项目，一定绕不开 MCP 这三个字母。我最早接触这个词的时候也一头雾水，翻了大半天官方文档才搞明白，它就是让 Claude 能调用外部工具和数据的统一协议。说白了，没有 MCP 的 Claude Code，只是一个会聊天的代码助手；接上 MCP 之后，它才能真正读你的文件、查你的数据库、操作你的浏览器。这篇东西适合两类人看：一类是刚装好 Claude Code、打算接 MCP 但不知道从哪下手的，另一类是已经在折腾、但被各种报错卡住想找答案的。我会从原理讲到实操，再把常见的坑挨个点一遍，争取让你看完就能照着做。

1. 先把 MCP 的定位弄清楚：它到底给 Claude Code 带来了什么

1.1 MCP 解决了什么问题

很多人以为 MCP 是一个软件、一个插件，其实它是一个协议（Protocol），学名 Model Context Protocol，是 Anthropic 提出的开放标准。它的目标是统一 AI 模型与外部工具之间的通信方式。

要理解它，我打个比方：没有 MCP 之前，每个 AI 工具要对接一个外部服务，都得单独写一套适配代码，就像家里买了一堆电器，每个电器都自带一种专用插座，墙上的插口还都不一样。你为了接一个硬盘，要买个转接头；接一个打印机，又要买另一个转接头。MCP 干的事，就是制定一个统一的 USB-C 标准：AI 这边提供标准插口，工具那边也按标准做插头，接上就能用。

具体到 Claude Code，MCP 解决的是三个很实际的痛点：

• 让 Claude 能安全地读写本地文件、执行命令、访问网络资源，而不是被限制在对话框里；
• 让 Claude 能通过统一方式连接数据库、浏览器、测试工具、设计软件等专业工具；
• 让同一个 MCP Server 可以在不同的 AI 客户端之间复用，比如今天在 Claude Code 里用，明天换到 Claude Desktop 或者别的编辑器，配置方式基本一致。

正常来说，Claude Code 本身也内置了一些能力，比如读写文件、执行 shell 命令。但它的能力边界是固定的，你想让它调一下你本地 MySQL，或者控制一下浏览器去点按钮，就得靠外部工具。MCP 就是把这些外部工具接入 Claude Code 的标准通道。

1.2 三种角色和两种传输方式

在 MCP 架构里，有三个角色：MCP Host（宿主）、MCP Client（客户端）、MCP Server（服务端）。Claude Code 启动后，它既是 Host 也是 Client 的载体，负责和模型对话；MCP Server 是真正干活的进程，比如"文件系统服务器""数据库服务器"；Claude 通过 MCP Client 作为中介，把工具调用请求发给 Server，再把结果拿回来。

传输方式上，现在主流是两种：

• stdio（标准输入输出）：Server 作为子进程在本地运行，和 Claude Code 通过管道通信。适合本地工具，比如文件系统、Git 操作。配置时只要填 command 和 args 就行。
• HTTP/SSE 或 WebSocket：Server 运行在远程或独立进程里，通过 HTTP 或 WebSocket 通信。适合远程服务、多用户共享服务。配置时需要填 url，有些还要填 token 或 headers。

我见过很多人配置远程 MCP 时总把wss://和https://搞混，这里提醒一句：wss://是 WebSocket 加密连接，通常用在长连接、需要实时推送的场景；https://是普通 HTTP 接口。MCP 远程服务器给了什么协议头，你就用什么协议头，别自己随手改。搞清楚这两种传输方式的区别，后面看配置项就不会晕。

还有一个容易忽略的点：MCP Server 的功能不是固定的，它取决于你怎么写、怎么组合工具。一个简单的文件系统服务器可以让你做文件的增删改查，一个 Playwright MCP 可以让 AI 驱动浏览器自动填表单、截图、调试页面。所以"MCP 有什么用"这个问题，实际上是"你想让 AI 替你干什么"，然后去找对应的 Server，或者自己写一个。

2. 装前准备：把 Claude Code 和依赖环境一次搞定

2.1 安装 Node.js 并确认版本

Claude Code 本身是一个 Node.js 应用，MCP Server 大部分也是通过 npx 启动的 Node 包，所以 Node 环境是硬前提。官方要求 Node 18 以上，但我实际用下来，建议直接装 Node 20 或 22 的 LTS 版本。为什么？因为很多新的 MCP Server 已经在用 Node 20 才有的 API，版本低了会报一些莫名其妙的错，你还不容易联想到是 Node 版本问题。

装完之后，打开终端验证一下：

node -v npm -v

如果提示找不到 node 或 npm，说明环境变量没配好。Windows 上常见的问题是安装时没勾选"Add to PATH"，此时需要手动把 Node 安装目录加进系统环境变量的 Path 里，然后重开终端。macOS 上如果用了 nvm，还要注意 nvm 默认 Node 版本是不是你刚装的这个，用nvm ls可以查看，用nvm use切换。

2.2 安装 Claude Code 本体

Node 环境没问题之后，安装 Claude Code 就是一条命令的事：

npm install -g @anthropic-ai/claude-code

这里我用的是全局安装，好处是终端里任何目录都能直接敲claude。如果你不想全局装，也可以放在项目里通过 npx 调用，但我个人还是推荐全局，因为 Claude Code 本身就是个终端工具，全局安装最顺手。

安装完成后验证一下：

claude --version

如果能正常输出版本号，就说明装好了。然后直接运行claude进入交互界面，按照提示完成登录认证。认证方式一般有扫码登录和使用 API Key 两种，根据你自己的账号情况选一种就行。

2.3 顺手把 Git 和基础工具装好

如果你打算用 Claude Code 管理代码仓库，Git 是少不了的。Windows 上装 Git 的时候，注意安装选项里有个"Adjust your PATH environment"一定要选第二项或第三项，否则 Git 命令在终端里不可用。macOS 一般自带 Git，但如果之前装过 Xcode 命令行工具，通常也是可用的。

另外提一句，很多人问到 VS Code 里怎么配置 Claude Code。Claude Code 现在有桌面版，也可以在 VS Code 的终端里直接跑，本质还是同一个命令行工具，MCP 配置完全互通。你前面在这个终端里配好的 Server，换到那个终端一样生效，因为配置文件是写在用户目录下的。

3. 上手配置：三分钟把第一个 MCP Server 挂上去

3.1 方式一：用命令行命令添加

Claude Code 提供了一组claude mcp子命令，最常用的就是 add、list、remove。下面这条命令把官方的文件系统 MCP Server 添加进来：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

拆开说明一下：filesystem是给这个 Server 起的名字，你可以随意命名，但建议见名知意；--后面是真正要执行的启动命令，npx 会临时下载并运行这个 npm 包；最后那个路径参数/Users/me/projects表示允许这个 Server 访问的目录范围。

运行完可以用claude mcp list查看所有已配置的 Server，输出里会显示名字、传输方式、命令和状态。如果要删除某个 Server，用claude mcp remove filesystem就行。

这里有个小参数值得单独说：--scope。它决定这个 Server 配置是只对当前项目生效，还是对当前用户所有项目生效。

claude mcp add mysql --scope user -- npx -y @some/mysql-server

默认情况下，大部分配置写进用户级文件；如果你加了--scope project，就会写进当前项目的配置。团队协作时，项目级配置可以跟着仓库走，其他人拉下来就能用。

3.2 方式二：直接编辑 .mcp.json 配置文件

命令行虽然方便，但如果你想精确控制参数、或者配置文件要提交到仓库里给团队共用，手写 .mcp.json 更合适。在项目根目录新建一个.mcp.json文件，内容长这样：

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects" ] } } }

这个 JSON 结构其实很好理解：最外层固定是mcpServers，里面每个 key 是 Server 名字，value 是这个 Server 的启动配置。stdio 类型要写 command 和 args；env 字段可以塞环境变量；远程服务器类型则写成 url、headers 这种形式。

使用配置文件方式的好处是可视化和可维护性更好。命令行方式写进的是~/.claude.json，那是一长串 JSON，人类没法读；而.mcp.json在项目里清清楚楚，出了问题也容易排查。我现在的习惯是：临时测试用命令，正式项目用配置文件。

3.3 配置远程 MCP Server 的格式

这两年第三方云 MCP 服务越来越多，很多服务商会给你一个类似这样的地址：

wss://api.example.com/mcp/?token=your_token_here

这种远程 Server 在.mcp.json里配置格式如下：

{ "mcpServers": { "cloud-mcp": { "url": "wss://api.example.com/mcp/?token=your_token_here", "enabled": true } } }

注意，这里的 url 是服务商完整提供的，token 不要泄露到公开仓库。如果你把.mcp.json提交到 Git 仓库，建议用环境变量占位的方式，或者干脆把这种远程配置放进用户级配置，避免 token 被同事或开源社区看到。

远程 MCP 连接不上时，大多数情况是网络策略问题：目标域名或端口没有放行。你自己本地的防火墙、企业网络的访问控制，都会影响这个wss://连接。排查的时候先确认本地网络能访问这个域名，而不是一上来就怀疑配置写错了。

4. 实战配置：数据库和浏览器两个高频场景

4.1 给 Claude Code 接上 MySQL：让 AI 帮你查库

数据库是 MCP 用得最多的场景之一。配置之前，你得先确保本地有一个能连上的 MySQL 实例。如果你还没装 MySQL，那就先装好并启动服务，确保用命令行能登录进去，比如mysql -u root -p能成功，然后再来做 MCP 配置。

这里我用社区常用的 MySQL MCP Server 做示范，在.mcp.json里配置如下：

{ "mcpServers": { "mysql": { "command": "npx", "args": [ "-y", "@designcomputer/mysql_mcp_server" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "yourpassword", "MYSQL_DB": "your_database" } } } }

这套环境变量字段是这个包约定的，不同数据库 Server 包的字段名可能会有差别，配置前最好看一眼对应包的说明。配好之后，在 Claude Code 里直接问"帮我查一下 users 表里有哪些字段"，如果 MCP 生效，它会先调用 mysql 工具执行 SQL，然后基于结果回答你。

我实际用下来有一个体会：MCP 帮你写 SQL 很爽，但也危险。数据库 Server 给了 Claude 完整的读写权限，如果你在对话里说"删掉重复数据"，它可能真的会执行 DELETE。所以测试环境随便折腾，生产环境千万别配 MCP，或者至少用只读账号。

4.2 给 Claude Code 接上浏览器：用 Playwright MCP 做网页自动化

前端开发的同学用 Playwright MCP 会比较顺手。它的作用是让 Claude 能控制浏览器页面，比如打开网页、点击按钮、输入文本、截图、提取 DOM 信息。配置很简单：

{ "mcpServers": { "playwright": { "command": "npx", "args": [ "-y", "@playwright/mcp@latest" ] } } }

第一次配置完成后，Claude Code 启动这个 Server 时会自动下载对应版本的浏览器内核，这个过程可能需要几分钟，而且依赖网络状态。如果你在终端手动执行npx -y @playwright/mcp@latest能正常启动、不报错，说明浏览器下载好了，再接进 Claude Code 就会很顺。

用 Playwright MCP 之后，你可以对 Claude 说"打开 example.com，点击登录按钮，把页面截图保存到本地"，它会真的去操作浏览器，这对写爬虫脚本、做端到端测试、排查页面样式问题都很有用。不过同样要提醒：给它的权限越大，翻车概率越高；页面上的操作不可控性比数据库还高，别让它操作你没把握的页面。

4.3 如何验证 MCP 是否真正生效

配置写了一堆，怎么确认真的生效了？两种方法。

第一种，在 Claude Code 交互界面里敲/mcp，它会列出所有 Server 和连接状态，显示 connected 才是真的接上了。第二种，直接问 Claude："你现在可以使用哪些工具？"它会在回答里列出通过 MCP 加载的工具。如果它说没有额外工具，说明配置有问题，或者 Server 启动失败了。

还有一种更直接的验证方式：开一个最简单的文件系统 Server，让它读写一个测试文件。如果文件能创建、能读取，说明 MCP 链路是通的；如果这一步都不通，那问题多半出在环境或启动命令上，而不是你具体用什么 Server。这个方法我建议每个初学 MCP 的人都先做一遍，花两分钟，能少走很多弯路。

5. 高频报错排查：我把撞过的墙都列出来

5.1 报错速查表

下面这个表格是我在配置 MCP 时实际遇到过的、以及帮别人排查时最常见的问题，直接拿去对照：

EACCES 这个我想多说两句。很多人在 macOS 或 Linux 上全局安装 npm 包的时候，报权限错误，第一反应是加 sudo。短时间看是搞定了，但用 sudo 装的全局包后续经常出诡异问题，比如某些包写文件时权限不一致、Claude Code 读配置文件时没权限。更推荐的做法是用 nvm 装 Node，这样整个 npm 全局目录都在你的用户权限下，不会踩这个坑。

5.2 一条排查方法论：先手动、再分离、后看日志

很多报错看似吓人，其实问题很基础。我总结的排查步骤，按顺序走基本都能解决。

第一步，手动跑命令。把.mcp.json里 command 和 args 拼出来的命令，复制到终端直接执行一次。如果这一步就报错，那和 Claude Code 一点关系都没有，纯粹是 Server 本身启动不了。你先在这里把问题解决，再回过来看 MCP 配置。这一步能过滤掉 70% 的问题。

第二步，检查配置分离度。如果手动能跑起来，但 Claude Code 里连不上，那就把问题拆开：先用最简单的官方文件系统 Server 配置一遍，看能不能连；如果最简单的能连，复杂的不能连，那问题出在复杂 Server 的参数上；如果简单的也不能连，那问题出在 Claude Code 加载方式、或者是环境变量、路径上。

第三步，看日志。Claude Code 支持调试模式，启动时加--debug参数可以输出详细日志。MCP 相关的报错信息都会打在日志里。我见过有人卡了几个小时，打开 debug 日志一看，原来是 Server 端因为缺少某个系统库启动失败，日志里写得很清楚，只是之前根本没看。

还有一个值得提的排查技巧：配置的 env 环境变量。很多 Server 报"连接失败"不是真的连不上，而是它通过环境变量读数据库密码时读到空的。你在 .mcp.json 里填了 env，但注意环境变量不能通过命令行方式添加，只能通过编辑配置文件。如果使用claude mcp add添加 Server 时想带环境变量，我建议直接改用配置文件方式，这是最不容易出错的路径。

5.3 关于模型兼容与网关的常见疑问

经常有人问我："我用的不是 Claude 官方 API，而是通过兼容网关接入 DeepSeek 或者其他模型，MCP 还能用吗？"答案是可以。因为 MCP 是工具层、是协议层，它不关心你后面跑的是哪一个大模型。只要 Claude Code 能正常发起对话、能够调用工具，MCP 的配置方式完全一样。区别只在于模型本身的工具调用能力：有些模型对工具调用的服从性差一些，可能会少调用或者乱调用工具，那是模型层面的问题，不是 MCP 配置的问题。

这个点想清楚之后，你会发现 MCP 其实很独立：协议是开放的，Server 是社区生态的，客户端是通用的。今天你用的工具，明天换个模型、换个客户端，这套配置很多还能复用，这也是我花这么久写 MCP 文档的原因，投入一次，长期受益。

6. 我的实操心得和最后几个建议

玩 MCP 这段时间，最大的体会是：配置本身不难，难的是理解每个报错背后的机制。很多时候你觉得是配置错了，其实是环境问题；你觉得是环境问题，其实又是 Server 包本身的 bug。所以我的建议始终是：先手动、再分离、后看日志，按这个流程走，没有解不了的题。

如果你是从零开始，我建议你按这个顺序来：先把官方文件系统 MCP 配通，验证链路没问题；再根据自己的实际需求，挨个加上数据库、浏览器这些 Server。一次只加一个，加完立刻验证，别一口气配了一堆，最后全连不上，你根本分不清是哪个的问题。

另外提醒一下文件权限和安全性。MCP 给了 Claude 调用真实工具的能力，这是双刃剑。给文件系统 Server 指定一个专门的工作目录，给数据库 Server 用只读账号，给浏览器 Server 加访问白名单，这些安全习惯越早养成越好。我见过有人把整个用户目录都开放给文件系统 Server，结果 Claude 在对话中不小心删了项目目录里的重要文件，这种事故只要在配置时缩小目录范围就能完全避免。

MCP 生态还在飞速发展，今天写的配置方式，过几个月可能就有更简单的替代方案。但核心原理——Client、Server、协议、stdio 和 WebSocket 两种传输方式——是不变的。把原理吃透，以后不管出什么新工具，你都能快速上手。

最后再分享一个小技巧：建议把项目里的.mcp.json纳入版本管理，同时写进.gitignore一个.mcp.local.json之类的文件，用于存放带密码、token 的本地配置。这样团队成员拉下项目，天然就有一套安全的 MCP 配置，每个人只需要补上自己的密钥文件就行。这也是我在团队协作里踩过坑之后总结出来的做法，分享给你。