Claude Code 添加 MCP 服务器配置指南

Claude Code 添加 MCP 服务器完整指南

什么是 MCP？

MCP 是 Anthropic 推出的开源通信标准，它就像是 AI 助手的'手脚'，让 Claude Code 可以：

• 📁 直接访问和操作本地文件系统
• 🌐 连接各种 API 和网络服务
• 🗄️ 查询和操作数据库
• 🛠️ 集成各种开发工具

🔧 自动化日常任务

30 秒快速上手

如果你赶时间，这是最快的添加方法：

# 添加文件系统访问（最常用）
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop

# 验证是否成功
claude mcp list

就这么简单！但如果遇到错误，请继续阅读详细指南。

详细添加步骤（3 种方法）

方法 1：命令行添加（推荐新手）

Claude Code 提供了简单的命令行工具来添加 MCP 服务器：

方法 2：直接编辑配置文件（推荐高级用户）

很多开发者觉得 CLI 向导太繁琐，特别是输错了要重来。直接编辑配置文件更高效：

1. 找到配置文件位置：

   • macOS/Linux: ~/.claude.json
   • Windows: %USERPROFILE%\.claude.json

2. 编辑配置文件：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"],
      "env": {}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "your-github-token"}
    }
  }
}

3. 重启 Claude Code 生效

方法 3：项目级配置（推荐团队协作）

如果你想让团队成员都能使用相同的 MCP 配置：

# 添加项目级 MCP 服务器
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools

这会在项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "shared-tools": {
      "command": "npx",
      "args": ["-y", "@your-team/mcp-tools"],
      "env": {}
    }
  }
}

MCP 服务器作用域详解

理解作用域对于避免'找不到服务器'的错误至关重要：

1. Local 作用域（默认）

   • 只在当前目录可用
   • 配置存储在 ~/.claude.json 的 projects 部分
   • 适合：个人项目特定工具

2. User 作用域（全局）

   • 在所有项目中都可用
   • 使用 -s user 标志添加
   • 适合：常用工具如文件系统、数据库客户端

3. Project 作用域（团队共享）

   • 通过 .mcp.json 文件共享
   • 使用 -s project 标志添加
   • 适合：团队共享的项目特定工具

10 个最实用的 MCP 服务器推荐

基于社区反馈和实际使用经验，这是最值得安装的 MCP 服务器列表：

1. 文件系统访问

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

用途：让 Claude 直接读写文件，修改代码

2. GitHub 集成

claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

用途：管理 issues、PRs、代码审查

3. 网页浏览器控制

claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer

用途：自动化网页操作、爬虫、测试

4. 数据库连接（PostgreSQL）

claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgres

用途：直接查询和操作数据库

5. Fetch 工具（API 调用）

claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch

用途：调用各种 REST API

6. 搜索引擎

claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

用途：搜索最新信息

7. Slack 集成

claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slack

用途：发送消息、管理频道

8. 时间管理

claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time

用途：时区转换、日期计算

9. 内存存储

claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

用途：跨对话保存信息

10. Sequential Thinking（思维链）

claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

用途：复杂问题分步骤思考

常见错误及解决方案

错误 1：工具名称验证失败

API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'"

解决方案：

• 确保服务器名称只包含字母、数字、下划线和连字符
• 名称长度不超过 64 个字符
• 不要使用特殊字符或空格

错误 2：找不到 MCP 服务器

MCP server 'my-server' not found

解决方案：

1. 检查作用域设置是否正确
2. 运行 claude mcp list 确认服务器已添加
3. 确保在正确的目录下（对于 local 作用域）
4. 重启 Claude Code

错误 3：协议版本错误

"protocolVersion": "Required"

解决方案： 这是 Claude Code 的已知 bug，临时解决方案：

1. 使用包装脚本
2. 确保 MCP 服务器返回正确的协议版本
3. 更新到最新版本的 Claude Code

错误 4：Windows 路径问题

Error: Cannot find module 'C:\\Users\\username\\Documents'

解决方案： Windows 路径需要使用正斜杠或双反斜杠：

# 错误
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents

# 正确
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
# 或
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Documents

错误 5：权限问题

Permission denied

解决方案：

1. macOS/Linux：使用 sudo（不推荐）或修改文件权限
2. Windows：以管理员身份运行
3. 最好的方法：将 MCP 服务器安装在用户目录

调试技巧

当遇到问题时，这些调试方法可以帮你快速定位：

1. 启用调试模式

claude --mcp-debug

2. 查看 MCP 状态

在 Claude Code 中输入：

/mcp

3. 查看日志文件

macOS/Linux:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

type "%APPDATA%\Claude\logs\mcp*.log"

4. 手动测试服务器

# 直接运行服务器命令，看是否有输出
npx -y @modelcontextprotocol/server-filesystem ~/Documents

中文用户特别注意事项

对于国内开发者来说，除了技术层面的问题，还需要关注一些特殊情况。

1. 中文路径问题

避免在路径中使用中文字符：

# 避免
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档

# 推荐
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

2. 代理配置

如果你在使用代理：

# 设置 npm 代理
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# 然后再添加 MCP 服务器
claude mcp add ...

3. 国内镜像源

使用淘宝 npm 镜像加速下载：

# 临时使用
claude mcp add fs -- npx -y --registry=https://registry.npmmirror.com @modelcontextprotocol/server-filesystem ~/Documents

# 或永久设置
npm config set registry https://registry.npmmirror.com

最佳实践建议

1. 按需添加：不要一次性添加太多 MCP 服务器，会影响性能
2. 定期清理：使用 claude mcp remove <name> 删除不用的服务器
3. 安全第一：只添加可信的 MCP 服务器，特别是需要网络访问的
4. 备份配置：定期备份 ~/.claude.json 文件
5. 团队协作：使用 project 作用域共享常用配置

进阶技巧

1. 创建自定义 MCP 服务器

如果现有的 MCP 服务器不能满足需求，可以创建自己的：

// my-mcp-server.js
import { Server } from '@modelcontextprotocol/sdk';

const server = new Server({
  name: 'my-custom-server',
  version: '1.0.0',
});

server.setRequestHandler('tools/list', async () => {
  return {
    tools: [{
      name: 'my_custom_tool',
      description: '自定义工具',
      inputSchema: {
        type: 'object',
        properties: {
          input: { type: 'string' }
        }
      }
    }]
  };
});

server.start();

2. 批量配置脚本

创建一个脚本一次性配置所有常用 MCP 服务器：

#!/bin/bash
# setup-mcp.sh
echo "正在配置常用 MCP 服务器..."

# 文件系统
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

# GitHub
read -p "请输入 GitHub Token: " github_token
claude mcp add github -s user -e GITHUB_TOKEN=$github_token -- npx -y @modelcontextprotocol/server-github

# 其他服务器...
echo "配置完成！"
claude mcp list

总结

通过本文，你应该已经掌握了：

1. ✅ 三种添加 MCP 服务器的方法
2. ✅ 作用域的概念和使用场景
3. ✅ 10 个最实用的 MCP 服务器
4. ✅ 常见错误的解决方案
5. ✅ 调试和优化技巧

MCP 让 Claude Code 从一个简单的 AI 助手变成了强大的开发伙伴。正确配置 MCP 服务器后，你的开发效率将会大幅提升。