Claude Code MCP 配置与实战：从接入到熟练使用

Claude Code 本身具备代码理解与执行能力，但当任务涉及本地文件、GitHub、数据库或浏览器时，还需要一套统一的外部工具连接机制。MCP 正是承担这一角色的标准协议。接下来将从服务器添加与作用域配置入手，逐步说明传输方式、配置文件结构、工具调用以及常见连接问题的处理方法。

Claude Code MCP 使用教程——从入门到精通

一、什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 于 2024 年 11 月推出的开源标准协议，旨在统一 AI 大模型与外部工具、数据源之间的通信方式。你可以把 MCP 理解为 AI 世界的 USB-C 接口——通过一个标准化的协议，让 AI 助手能够直接访问文件系统、数据库、API、浏览器等各种外部资源。

在 Claude Code 中，MCP 是其扩展能力的核心机制。通过连接 MCP 服务器，Claude Code 可以：

• 读取和写入本地文件
• 操作 GitHub 仓库（创建 Issue、PR、代码搜索）
• 查询数据库
• 控制浏览器进行自动化操作
• 调用各种 Web API

MCP 分为三个角色：MCP 主机（如 Claude Code、Claude Desktop）、MCP 客户端（协议客户端）、MCP 服务器（提供具体工具和资源的中间件）。

二、Claude Code 中的 MCP 配置方式

Claude Code 支持多种配置 MCP 服务器的方式，从简单到高级，满足不同场景需求。

2.1 使用 claude mcp 命令（推荐）

这是最简单、最推荐的方式。Claude Code 提供了专门的交互式 CLI 命令来管理 MCP：

# 查看所有已配置的 MCP 服务器
claude mcp list

# 添加一个新的 MCP 服务器
claude mcp add <服务器名称> [选项] -- <启动命令>

# 移除一个 MCP 服务器
claude mcp remove <服务器名称>

# 交互式 MCP 配置界面
claude mcp

作用域（Scope）选项

MCP 配置有三个作用域层级：

作用域	命令参数	配置文件位置	适用场景
项目级	-s project （默认）	项目根目录的 .mcp.json	团队共享的工具
用户级	-s user	~/.claude/settings.json	个人常用工具
全局级	-s global	Claude Code 全局配置	所有项目都可用

示例：

# 项目级：仅供当前项目使用
claude mcp add filesystem -s project -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 用户级：当前用户的所有项目都可用
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 全局级：所有用户和项目都可用
claude mcp add filesystem -s global -- npx -y @modelcontextprotocol/server-filesystem /path

2.2 两种传输方式（Transport）

MCP 服务器可以通过两种方式与 Claude Code 通信：

stdio 传输（本地服务器）

服务器作为子进程运行，通过标准输入/输出通信。适用于运行在本地机器上的工具。

claude mcp add myserver -- npx -y @modelcontextprotocol/server-filesystem /path

HTTP 传输（远程服务器）

服务器运行在远程，通过 HTTP/SSE 通信。适用于云服务。

claude mcp add myserver --transport http -- https://api.example.com/mcp

2.3 手动编辑配置文件

如果你更喜欢手动编辑，也可以直接修改配置文件。

项目级配置（.mcp.json，放在项目根目录）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

用户级配置（~/.claude/settings.json）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

三、添加 MCP 服务器的完整流程

3.1 查找可用的 MCP 服务器

• 官方参考服务器：github.com/modelcontex…
• MCP 注册中心：mcp.so
• Awesome MCP Servers：mcpservers.org

3.2 添加一个 MCP 服务器

以添加文件系统服务器为例：

# Step 1: 确认 Node.js 已安装
node --version

# Step 2: 使用 claude mcp add 命令添加
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# Step 3: 验证是否成功
claude mcp list

3.3 添加需要环境变量的服务器

有些 MCP 服务器需要 API Key 等敏感信息，可以通过 -e 或 --env 参数传入：

claude mcp add github -s project -e GITHUB_TOKEN=ghp_your_token_here -- npx -y @modelcontextprotocol/server-github

你也可以指定多个环境变量：

claude mcp add myserver 
  -e API_KEY=abc123 
  -e API_BASE=https://api.example.com 
  -- npx -y my-mcp-server

3.4 在对话中使用 MCP 工具

添加成功后，在 Claude Code 的对话中直接描述你的需求即可——Claude Code 会自动调用已安装的 MCP 工具。

例如添加了 GitHub MCP 后，你可以说：

"列出这个仓库最近的 issues" "帮我创建一个 PR" "搜索代码中包含 'auth' 的所有文件"

Claude Code 会识别你的意图，自动选择合适的 MCP 工具来执行。

3.5 查看当前连接的 MCP 服务器

claude mcp list

这会显示所有已配置的 MCP 服务器及其连接状态。

四、MCP 配置详解

4.1 配置文件结构

.mcp.json 或 settings.json 中的 MCP 配置结构如下：

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name", "arg1", "arg2"],
      "env": {
        "KEY": "value"
      },
      "transport": "stdio"
    }
  }
}

字段	说明	必填
command	要执行的命令	是
args	命令参数数组	否
env	环境变量对象	否
transport	传输方式（stdio 或 http）	否，默认 stdio

4.2 配置文件优先级

Claude Code 按照以下顺序合并配置（后面的覆盖前面的）：

1. 全局配置
2. 用户级配置（~/.claude/settings.json）
3. 项目级配置（./.mcp.json）

五、高级用法

5.1 使用 Docker 运行 MCP 服务器

有些 MCP 服务器推荐使用 Docker 运行：

claude mcp add github-mcp 
  -e GITHUB_TOKEN=ghp_your_token_here 
  -- docker run -i --rm 
    -e GITHUB_TOKEN 
    ghcr.io/github/github-mcp-server

5.2 通过插件安装 MCP

Claude Code 的插件（plugin）可以自动捆绑 MCP 服务器配置。安装插件后，MCP 服务器会自动配置好，无需手动操作：

# 安装 Figma 插件（自动配置 Figma MCP）
claude plugins install figma

5.3 修改 MCP 输出 Token 限制

Claude Code 默认在 MCP 工具输出超过 10,000 tokens 时会显示警告。如果需要，可以通过环境变量增加限制：

export MAX_MCP_OUTPUT_TOKENS=50000

5.4 动态工具更新

Claude Code 支持 MCP 的 list_changed 通知——MCP 服务器可以动态更新其可用工具、提示和资源，无需你断开重连。

5.5 排查 MCP 连接问题

如果 MCP 服务器连接失败，可以按以下步骤排查：

1. 检查服务器是否安装正确

   claude mcp list
   

2. 检查环境变量是否正确

   # 手动运行命令测试
   npx -y @modelcontextprotocol/server-github
   

3. 重新启动 Claude Code 有时需要重启会话才能加载新配置。

4. 检查配置文件语法 确保 JSON 格式正确，没有多余的逗号。

5. 查看 Node.js 版本

   node --version  # 需要 Node.js 18+
   

六、安全和最佳实践

6.1 安全注意事项

• 只添加可信的 MCP 服务器——特别是那些需要网络访问或文件系统权限的服务器
• 谨慎使用全局作用域——只需要在多个项目中使用的工具才设为 global
• 定期审计配置——运行 claude mcp list 检查当前启用了哪些 MCP 服务器
• API Key 安全——使用 -e 参数而不是在配置文件中硬编码密钥

6.2 最佳实践

• 项目级 vs 用户级：团队共享的工具用 project 作用域，个人工具用 user 作用域
• 按需添加：不要一次性添加太多 MCP 服务器，以免增加上下文负担
• 验证可用性：添加后立即测试，确保服务器正常工作
• 定期更新：MCP 服务器生态发展很快，定期检查更新
• 利用 Tool Search：Claude Code 的 Tool Search 功能会自动从已配置的 MCP 服务器中搜索最相关的工具，保持上下文高效

七、总结

MCP 是 Claude Code 扩展能力的关键。通过本文介绍的 claude mcp add 命令和配置文件方式，你可以轻松地将 Claude Code 连接到文件系统、GitHub、数据库、浏览器等各种外部工具。

核心记忆口诀：

• 添加：claude mcp add <名称> [选项] -- <启动命令>
• 查看：claude mcp list
• 移除：claude mcp remove <名称>
• 作用域：project（默认）、user、global
• 传输：stdio（本地）、http（远程）

下一篇文章我将介绍最推荐的 MCP 服务器及其详细的安装步骤和使用手册。