企业官网建设流程全解析

最近这段时间，我把手头好几个重复性开发任务都交给了 Claude Code，再通过 MCP（Model Context Protocol，模型上下文协议）把浏览器、设计稿、建模软件和一堆常用工具统一接到同一个会话里。这篇文章就是围绕 Claude Code 与 MCP 服务器使用的一次完整复盘——包含我踩过的坑、写过的配置、以及自建服务器时那些容易被忽略的运维细节。如果你正准备入门 AI 编程助理，或者已经在用但想把 MCP Server 玩明白，这篇文章应该能帮你省下不少时间。

先简单交代背景。网上关于 Claude Code 的教程不少，但多数停在“怎么安装、怎么问答”的层面，真正把 MCP 服务器接入流程、配置参数、常见报错讲透的不多。我这次从零开始，把安装、接线、自建服务到排错一条线走完，适合三类读者：刚接触 AI 编程想快速上手的开发者，已经在用 Claude Code 但对接第三方系统时被各种 MCP 报错卡住的工程师，以及需要维护自建工具的运维同学。文章里所有命令和配置文件都是我实际跑过的，版本差异导致的小变化我会在对应位置提醒。

1. Claude Code 的安装与环境准备

1.1 先装好运行环境：Node.js 版本不能太老

Claude Code 是命令行程序，底层跑在 Node.js 上。所以第一步不是急着装它，而是确认你的 Node.js 版本。我实测下来，Node.js 18 以上才比较稳，Node 20 和 22 是我用得最多的版本，如果你机器上还是 16 这种老版本，建议先升级。

检查版本很简单：

node -v npm -v

如果 node 版本太低，或者机器上同时有多个 Node 环境，建议用 nvm 或 fnm 这类版本管理工具切到 LTS 版本。这里有个小坑：很多人装完 Node 后，npm 全局目录权限不对，导致后面安装 Claude Code 时报 EACCES 权限错误。Linux/macOS 下建议把 npm 全局目录设置在用户目录下，避免动不动就要 sudo；Windows 下则要留意 npm 全局 bin 目录是否已经加入 PATH。

1.2 一条 npm 命令完成安装

环境没问题后，安装本身就很简单了：

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

安装完成验证一下：

claude --version

能正常输出版本号就说明装好了。我第一次跑的时候习惯性想加 sudo，后来发现完全没必要，反而容易把全局目录的权限搞乱。如果你在国际网络环境下安装遇到下载慢或超时，可以临时把 npm 源切到国内镜像，装完再切回去，这是常规做法。装完后直接输入claude就能进入交互式终端，首次启动会让你在浏览器里做一个账号授权，授权完成后终端会显示当前工作目录和可用命令提示，这时候你就有一个能正常对话的 AI 编程助理了。

1.3 在 VSCode 里用 Claude Code：两种方式各有讲究

很多人喜欢在 VSCode 里用，我试过两种方式：第一种最省事，直接在 VSCode 内置终端里开一个面板跑claude，这样既能看代码，又能跟 AI 对话，互不干扰。第二种是安装官方或社区提供的扩展，扩展能帮你记住工作区上下文，比如当前打开的文件夹、选中代码片段等，体验更细腻一些。

我的建议是：第一次接触就用内置终端，少一层配置，出问题也好排查；用得顺手了再上扩展。VSCode 里配置 Claude Code 时，环境变量是个重点。比如你需要设置 API Key 或者其他模型网关地址时，可以在 VSCode 的 settings.json 里加：

{ "terminal.integrated.env.linux": { "ANTHROPIC_API_KEY": "your_key_here" } }

这样每次新建终端都会自动带上这个环境变量，不用每次手动 export。需要注意，别把密钥硬编码到会被提交的配置文件里，建议把敏感信息放到.env文件，用dotenv或者 shell 脚本加载，后面我会详细说。

2. MCP 协议拆解：为什么说它一通百通

2.1 MCP 不是某个软件，而是一套接口标准

很多人初次听到 MCP 服务器，会误以为它是一个具体的软件，比如“是不是又出了个像 Nginx 那样的服务程序”。其实不对。MCP（Model Context Protocol）本质上是一套协议，它解决的是“AI 应用怎么跟外部工具对话”的标准化问题。在 MCP 出现之前，每家厂商都有自己的函数调用方案，你接一个工具就要专门写一套适配代码，生态非常割裂。MCP 做的事情就是定义一套通用规范——AI 应用只要实现了这个规范，就能连接所有实现了同样规范的服务器。

打个比方：MCP 就像是给 AI 接外设的 USB-C 口。以前是打印机一个口、显示器一个口、硬盘又一个口，现在统一之后，只要设备支持 USB-C，一根线就能通吃。这个类比理解到位了，你就明白为什么现在这个领域热度这么高——谁能把工具生态统一起来，谁就掌握了下一阶段的开发入口。

2.2 Host、Client、Server 三层模型

MCP 的架构分三层，很多人配置时被各种名词绕晕，其实记三个角色就够了：

• MCP Host：宿主应用，也就是 Claude Code 本身。它负责管理会话、调用模型、展示结果。
• MCP Client：宿主应用里负责跟某个服务器建立连接、维持通道的会话组件。一个 Host 里可以同时挂多个 Client，每个 Client 对应一个 Server。
• MCP Server：提供能力的后台服务，可以是本地进程，也可以是远程服务。它向外暴露三类能力——Tools（工具）、Resources（资源）、Prompts（提示模板）。

核心的利器是 Tools。模型可以通过工具定义了解到“我能调什么、参数是什么”，然后在推理过程中按需调用。比如一个文件系统 MCP 服务器会提供read_file、write_file、list_directory这类工具，模型说要读某个文件时，Host 就把这个调用发给 Server，Server 执行完把结果返回给模型。整个过程模型不需要知道文件在哪个磁盘、用什么编码，只要按协议传参数就行。

2.3 传输方式：本地 stdio 与远程 wss 端点

MCP 支持两种主流连接方式。一种是本地进程间通信，用标准输入输出（stdio）通讯，比如你配置一个命令让 Claude Code 去启动 Playwright 的 MCP 服务，它们之间就是通过 stdio 传递 JSON-RPC 消息。另一种是网络传输，走 Streamable HTTP 或 WebSocket 协议，地址形式一般是这样的：

wss://your-mcp-endpoint.example.com/mcp/?token=your_token_here

这种远程端点在自建服务或使用公共 MCP 网关时很常见。需要注意，连接方式不同，配置写法也不同，本地服务要写好command和args，远程服务只需要提供url和鉴权信息。下面这个是一个标准的.mcp.json配置文件片段：

{ "mcpServers": { "remote-mcp": { "url": "wss://your-mcp-endpoint.example.com/mcp/?token=your_token_here" }, "local-filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } }

这里有个容易踩的坑：本地服务和远程服务的字段不通用，很多人把url写进本地服务的配置里，结果 Claude Code 拿它当命令执行，自然报错。搞清传输方式的差异，排查问题能快很多。

3. 实战：我把 MCP Server 接进了日常工具链

3.1 Playwright MCP：让 AI 自己打开浏览器干活

日常开发里经常要写爬虫、跑页面测试、核对前端效果。以前这些都要自己开浏览器操作，现在我把 Playwright MCP 接进来之后，任务变得简单很多。安装方式是先全局安装包：

npm install -g @playwright/mcp

然后在 Claude Code 的配置目录里加入以下片段，推荐用claude mcp add命令加，它会自动帮你写入配置：

claude mcp add playwright -- npx @playwright/mcp@latest

或者直接改配置文件：

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

接完之后，你可以直接跟 Claude Code 说“打开某个页面，截图给我，看看按钮是不是被遮挡”，它就会自己驱动浏览器完成操作。我实测用来做前端回归测试特别好用，原先要写一整套 Playwright 脚本的活儿，现在用自然语言描述一遍就能跑起来。这里有个细节：新版包名是@playwright/mcp，老教程里写的@microsoft/playwright-mcp已经是旧包名了，配置的时候别用混。

3.2 Figma MCP：把设计稿信息直接喂给 AI

前端开发最烦的一件事就是“对着设计稿猜尺寸颜色”。Figma 官方提供了figma-developer-mcp工具，可以让 Claude Code 直接读取 Figma 文件里的 frame、图层、文本、颜色等信息。配置方式也不复杂，先在 Figma 账号里申请一个有读取权限的 Access Token，然后添加 MCP 服务：

claude mcp add figma -- npx -y figma-developer-mcp --figma-api-key=你的token

实际用下来，我让 AI 照着设计稿实现一个组件的场景里，它能正确说出某个按钮的圆角半径、字体大小、背景色十六进制值，省去了反复切图量尺寸的过程。需要提醒的是，Figma Token 权限要尽量只读，并且不要让 Token 出现在聊天记录里，否则等于把设计文件权限暴露给了 AI 会话的管理者。这类 Token 如果泄露，去 Figma 后台吊销重新生成就是唯一选择。

3.3 Blender MCP 与 NXOpen：桌面和工业软件也能接

除了 Web 工具，MCP 还能接入各种桌面软件。以 Blender 为例，社区流行的blender-mcp项目把 MCP Server 做成 Blender 插件，AI 通过 WebSocket 直接调用 Blender Python API。默认端口是 9876，安装步骤一般是两段：先在 Blender 偏好设置里安装插件并启动服务，再用 Claude Code 连接：

claude mcp add blender -- wss://localhost:9876

连接后可以自然语言操控建模、改材质、摆相机。这对我这种不常用 Blender 的人帮助很大，相当于有个助手帮你写 Python 脚本。工业软件方向也有类似项目，比如 NXOpen MCP，把西门子 NX 的二次开发接口包装给 AI 调用，做参数化建模自动化。这些项目共通点是把桌面软件的能力变成标准化接口，让 AI 不再局限于写代码本身。

3.4 安全测试工具的 MCP：Burp Suite 与 Yakit

在授权测试环境里，安全工具接入 MCP 的价值也很明显。Burp Suite 社区有多个 MCP Server 适配项目，常见做法是安装一个扩展模块，启动本地服务，然后在 Claude Code 里连接本地端口。Yakit 也有 MCP 能力，可以开放给 AI 调用扫描、资产解析等模块。Chrome DevTools MCP 则能让你直接用 AI 操作浏览器调试面板，看网络请求、执行 JS、分析性能数据。

这类工具接入前要特别确认运行环境，只能在你自己拥有或明确授权的目标上测试，不要拿着公共服务器的地址随手交给 AI 扫。这个原则我在团队里反复强调过，因为 AI 会话记录是可追溯的，出了事第一责任人还是操作的人，工具只是放大你的操作意图。

4. 自建 MCP 服务器时绕不开的运维问题

4.1 服务器选型与虚拟化：从一台机器到集群

如果你要长期跑自己的 MCP 服务，把服务部署在云服务器上比一直开着本地电脑靠谱得多。学生或者个人实验室用，各大云厂商的轻量应用服务器和特价学生机就够用了，不必买高性能物理机。部署方式上，我喜欢先用 KVM 或容器把服务隔离起来。KVM 虚拟化的好处是每个虚拟机能独立重启、快照、迁移，跑一些需要特定内核版本的服务特别方便；如果只是跑 Node.js 或 Python 服务，直接用 Docker 容器反而更轻。

实际工作中我给服务器做系统的时候，常规路径是这样：物理机装好宿主机系统，创建 KVM 虚拟机，分配好 CPU、内存、磁盘；虚拟机内部再部署 Docker，MCP 服务跑在容器里。这样的好处是宿主机挂了某个服务不影响其他虚拟机，而且排查问题时可以从宿主机层面做资源限制和网络隔离。如果你的服务访问量上来了，可以考虑在 Nginx 后面挂多台 MCP 服务实例做负载均衡，这就进入集群的范畴了——不过对大多数个人项目来说，一台 2 核 4G 的虚拟机就绰绰有余。

4.2 时间同步与签名验签：容易被忽略的“隐形故障”

自建服务的运维里，最容易被忽略的是系统时间同步。你可能觉得时间不准顶多显示错个几分钟，但在 MCP 服务里，时间偏移会直接导致 Token 校验失败、HTTPS 证书过期误报、签名验签流程报错。因为 JWT 类 Token 的nbf和exp字段都是按时间判断的，你的服务器时间比真实时间慢了两分钟，服务端可能就判定 Token 还未生效或已经过期。解决方法是配置 NTP 时间同步，Linux 上：

systemctl enable --now chronyd timedatectl set-ntp true

然后检查一下同步状态，确认没有 offset 过大的告警。如果企业环境要求请求加签名，你也要留意签名验签服务器的链路是否依赖精确时间。这个坑排查起来特别隐蔽，我第一次遇到远程 MCP 服务偶尔 401、偶尔成功时，查了半天鉴权逻辑，最后才发现是 VM 时钟漂移。排错顺序真的很重要。

4.3 运维兜底工具：RustDesk 自建远程桌面与串口网关

服务器出问题进不去 SSH 的时候，远程桌面是一个有效兜底。RustDesk 支持自建服务器，把 hbbs 和 hbbr 两个组件跑起来，客户端配置指向自己的服务器地址，就能在内网或公网环境远程操作桌面。这套方案比商业远程软件灵活，数据走自己的服务器，适合运维自建的 MCP 主机。配置方式不复杂，两条系统服务加两个端口放行即可，需要注意把密钥文件保管好，它对整个中继通信安全负责。

还有一类场景也值得提一下，就是硬件设备接入。如果你的 MCP 服务要读取 PLC、仪器仪表这类串口设备的数据，常见的做法是在设备旁边放一块 Linux 网关板，做网口转串口服务，把串口数据封装成 TCP 端口，MCP Server 再通过网络去读写这个端口。这样相当于用一层网关把古老接口翻译成现代网络服务，你写工具的时候就不用纠结驱动和电平转换的问题了。

5. 配置细节与常见问题排查

5.1 配置文件到底放哪、怎么写才不出错

Claude Code 的 MCP 配置一般位于项目根目录或用户目录下的.mcp.json。我的习惯是把公共工具（如 Playwright）放在用户级配置里，把项目专属配置放在项目根目录，这样换项目时不会丢失常用工具。配置内容大体分两类：一类是本地命令型，需要填command和args；另一类是远程服务型，只需要填url和按需的headers。注意路径分隔符的问题，Windows 下如果要用本地cmd启动某些工具，config 里常有转义导致的坑，建议优先用npx命令减少路径依赖。

调试配置可用内置命令检查：

claude mcp list claude mcp get playwright claude mcp remove playwright

每次修改配置后，需要重启会话或执行/mcp命令查看连接状态。我经常看到有人改了配置半天没反应，其实不是配置错了，而是会话没重新加载。

5.2 常见错误速查表

我把这段时间遇到的典型问题整理成了表格，现场排查时可以直接对照：

这里特别提一下最后一条，400 错误有时会返回一段服务器信息，很多新手会吓得不行，以为服务被攻击了。其实这是服务端框架默认行为，你要做的是学会抓包看响应全文，从里面定位真正错误码。同时在自己的服务器上做好错误页信息收敛，别把框架版本和堆栈原样抛给外部。

5.3 Token 与密钥管理：比功能更要上心

MCP 远程服务的端点经常直接带 Token 参数，比如wss://.../mcp/?token=xxx。这种 URL 一旦发到群里或写进博客，Token 就废了，别人可以直接拿它连接你的服务。我踩过这个坑之后总结了几条规矩：第一，带 Token 的完整 URL 永远不要进 Git 仓库；第二，Token 要有过期时间，定期轮换；第三，远程服务至少做一层访问频率限制，避免被刷。

本地配置方面，建议用.env文件集中管理密钥，然后让启动脚本注入环境变量。比如：

export FIGMA_API_KEY=$(grep FIGMA_API_KEY .env | cut -d '=' -f2)

这样即使配置文件被上传，真正的密钥也不会暴露。另外，如果你需要把 Claude Code 接到第三方兼容模型网关，比如接入 DeepSeek 这类服务，核心也就是配好 base_url、模型名和密钥，原理跟配置远程 MCP 端点几乎一样——只要模型能给出正确的工具调用格式，整条链路就能通。

6. 一点个人经验收尾

文章写到这里，最后说点实在的。我这几周实践下来的最大体会是：Claude Code 的首页提问能力只发挥了它三成价值，剩下七成在 MCP 这一层。不要一次性装几十个服务器，那是给自己找麻烦。先从两三个高频场景开始——比如文件系统、Playwright、Figma——跑顺了再加新工具，否则排查配置都排查不过来。

配置这方面，我建议把.mcp.json当作代码一样纳入版本管理。每次新增或修改服务器配置，写清楚变更理由，这样哪次更新把某个工具搞挂了，你能快速回滚。还有个小技巧：所有 MCP 服务的启动日志统一收集到固定目录，出问题时先翻日志再猜原因，速度会快非常多。这套工具链还在快速演进，配置格式偶尔会有调整，跟着官方更新日志走，别长期停留在老版本上就行。