平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“在Claude Code设置MCP服务器”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。
一、什么是 MCP 服务器？
- MCP（Model Context Protocol） 是一种让 Claude 获得“外部能力”的机制。
- 在这个场景下，它相当于 Claude 的“数字假肢”，赋予它访问文件系统、浏览器、网页抓取、搜索等功能。
- 常用 MCP 工具：
| 工具 | 功能 | 是否需 API Key |
|---|---|---|
| Sequential Thinking | 链式推理，减少幻觉 | 否 |
| Filesystem | 访问本地目录 | 否 |
| Playwright | 多浏览器自动化 | 否 |
| Puppeteer | Chrome 自动化（已弃用） | 否 |
| Fetch | HTTP 请求 / 抓取网页 | 否 |
| Browser Tools | DevTools 控制 / 截图 / 日志 | 否 |
| Brave Search | 网络搜索能力 | |
| Firecrawl | 高级网页抓取 |
# 基本 MCP 服务器 (单独安装)
顺序思考
claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
让 Claude 真正思考问题，而不是自信地胡编乱造。
文件系统访问（根据需更新路径）
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop ~/Downloads ~/Projects
让 Claude 访问你的文件。
Playwright（多浏览器自动化）
claude mcp add playwright -s user -- npx -y @playwright/mcp
Puppeteer（已弃用，但仍然有效）
claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer
看着你的浏览器自己操作，陷入存在主义的恐惧。
Web Fetching（Web 拿到）
claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch
从网站抓取内容。
浏览器工具
从实现思路看，让 Claude 访问你浏览器的控制台日志、网络流量，同时能够运行性能/可访问性审核。
步骤 1：安装 Chrome 扩展程序 — 从发布页面下载同时将其加载到 Chrome 的扩展管理器中。
步骤 2：启动中间件服务器（保持此终端打开）：
npx -y @agentdeskai/[email protected]
步骤 3：将 MCP 服务器添加到 Claude Code（在单独的终端中）：
claude mcp add browser-tools -s user -- npx -y @agentdeskai/[email protected]
步骤 4：打开 Chrome DevTools (F12) 同时找到 BrowserTools 标签。
Brave Search（需 API 密钥）
# 将 YOUR_API_KEY_HERE 替换为你的实际 Brave Search API 密钥 claude mcp add brave-search -s user -- env BRAVE_API_KEY=YOUR_API_KEY_HERE npx -y @modelcontextprotocol/server-brave-search
让 Claude 搜索网络并带回结果。
Firecrawl（高级网页抓取 — 需 API 密钥）
# 将 fc-YOUR_API_KEY 替换为你的实际 Firecrawl API 密钥 claude mcp add firecrawl -s user -- env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
实际处理时，当你需以工业级效率抓取网站，同时且对 robots.txt 没啥敬意的时候。
二、一键安装脚本（macOS / Linux）
可批量安装多个常用 MCP 工具：
bash <<'EOF'
echo " 正在安装 Claude MCP 服务器..."
claude mcp add sequential-thinking -s user
-- npx -y @modelcontextprotocol/server-sequential-thinking || true
claude mcp add filesystem -s user
-- npx -y @modelcontextprotocol/server-filesystem
~/Documents ~/Desktop ~/Downloads ~/Projects || true
claude mcp add playwright -s user
-- npx -y @playwright/mcp-server || true
claude mcp add puppeteer -s user
-- npx -y @modelcontextprotocol/server-puppeteer || true
claude mcp add fetch -s user
-- npx -y @kazuph/mcp-fetch || true
claude mcp add browser-tools -s user
-- npx -y @agentdeskai/browser-tools-mcp || true
echo "--------------------------------------------------"
echo "✅ MCP 注册完成。"
echo ""
echo "要启用浏览器工具，请在第二个终端中运行并保持打开："
echo " npx -y @agentdeskai/browser-tools-server"
echo "--------------------------------------------------"
claude mcp list
EOF
Windows 用户：可将上述命令改写为 .bat 文件或在命令前加上 cmd /c。
三、安装范围说明
| 参数 | 含义 | 设置文件位置 |
|---|---|---|
| -s user | 全局安装 | ~/.claude.json |
| -s local | 项目内安装 | 当前项目目录下的 .claude.json |
macOS 特殊说明：
- Claude Desktop 设置文件：
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Code 设置文件：
~/.claude.json - 两者的 MCP 设置是分开的。
四、常用问题与解决方案
| 问题 | 可能原因 | 解决方式 |
|---|---|---|
| MCP 显示连接但无响应 | 路径设置或通信异常 | 检查 claude mcp list 输出和日志 |
| 超时错误 | 执行时间过短 | 设置环境变量：export MCP_TIMEOUT=10000 |
| Windows 命令执行失败 | CMD 兼容问题 | 在命令前添加 cmd /c |
| Docker/WSL 无法通信 | 网络隔离 | 采用 host.docker.internal 作为主机地址 |
| Puppeteer 失效 | 工具已弃用 | 建议改用 Playwright MCP |
示例 .claude.json 设置：
"mcpServers": {
"browser-tools": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@agentdeskai/[email protected]"
],
"env": {
"BROWSERTOOLS_SERVER_HOST": "host.docker.internal",
"BROWSERTOOLS_SERVER_PORT": "3025"
}
}
}五、提示工程建议（Prompt Engineering）
Claude 可能不会主动采用 MCP 工具，需在提示中显式说明采用哪个 MCP。
作者建议的做法：
- 将项目说明拆分为多层 README（如主层、模块层、任务层）。
- 借助结构化提示，让 Claude 依据层级调用相应 MCP。
此方式能减少 Claude 误调用、提升推理一致性。
六、总结与建议
MCP 是让 Claude Code 拥有“外部能力”的核心机制。
借助脚本可更快启用常用工具，增强 Claude 的实用性。
注意区分：
- 全局 vs 局部设置；
- 不同系统路径差异；
- Puppeteer 弃用、Playwright 替代；
- WSL / Docker 通信问题。
在这个场景下，总的来说，Claude设置MCP这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。