Claude Code(八)MCP Server：连接万物的通用协议

在使用 Claude Code 的早期，我常常有一种”天才被关在小黑屋”的感觉。虽然它精通代码，但它看不见我运行中的 PostgreSQL 数据库，读不到 GitHub 上的 Issue 详情，也无法访问公司内部的知识库 API。

它被困在本地文件系统的沙箱里。

Model Context Protocol (MCP) 的出现，打破了这堵墙。如果说 USB 接口让电脑可以连接万物，那么 MCP 就是 AI 时代的 USB 协议。

本文记录了我如何利用 MCP 将 Claude Code 连接到外部世界，实现真正的数据互通。

更多关于 MCP 开源标准的信息，请参考：Model Context Protocol 官方文档

Core Principles：什么是 MCP？

Model Context Protocol (MCP) 是 Anthropic 牵头制定的一套开放标准。它的核心理念很简单：标准化 AI 模型获取上下文（Context）和执行动作（Action）的方式。

在没有 MCP 之前，如果我想让 Claude 访问 GitHub，我需要等待官方开发 “GitHub 插件”。如果我想让它访问我的私有数据库，我得自己写复杂的 Glue Code。

有了 MCP，我只需要运行一个符合标准的 MCP Server。Claude Code 作为 MCP Client，就能自动发现并使用这个 Server 提供的资源（Resources）和工具（Tools）。

架构图解

graph LR
    subgraph Claude_Code [Claude Code Client]
        Core[AI Model]
        Client[MCP Client 模块]
    end

    subgraph MCP_Layer [MCP Servers]
        GitHub[GitHub Server]
        DB[Postgres Server]
        Web[Browser Server]
    end

    subgraph Real_World [外部世界]
        Repo[代码仓库/Issues]
        Data[业务数据]
        Internet[互联网]
    end

    Core <--> Client
    Client -- JSON-RPC --> GitHub
    Client -- JSON-RPC --> DB
    Client -- JSON-RPC --> Web

    GitHub <--> Repo
    DB <--> Data
    Web <--> Internet

MCP 能做什么

通过 MCP 服务器，我可以让 Claude Code：

• 从问题跟踪系统实现功能：”添加 JIRA issue ENG-4521 中描述的功能，并在 GitHub 上创建 PR”
• 分析监控数据：”检查 Sentry 和 Statsig，分析 ENG-4522 功能的使用情况”
• 查询数据库：”基于我们的 PostgreSQL 数据库，找到使用 ENG-4523 功能的 10 个随机用户的邮箱”
• 集成设计：”根据 Slack 中发布的新 Figma 设计更新我们的标准邮件模板”
• 自动化工作流：”创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会话”

Practical Implementation：实战配置

安装方式概览

MCP 服务器可以通过三种不同的传输方式进行配置，具体取决于我的需求：

• HTTP 服务器：连接远程 MCP 服务的推荐选项，广泛应用于云端服务
• SSE 服务器：基于 Server-Sent Events 的传输方式（已弃用，建议使用 HTTP）
• Stdio 服务器：在本地机器上运行的服务器进程，适合需要直接系统访问或自定义脚本的工具

添加 HTTP 服务器

HTTP 服务器是连接远程 MCP 服务的推荐选项。这是最广泛支持的云端服务传输方式。

# 基本语法
claude mcp add --transport http <name> <url>

# 实际示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带有 Bearer token 的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

添加 SSE 服务器

SSE (Server-Sent Events) 传输已弃用。尽可能使用 HTTP 服务器。

# 基本语法
claude mcp add --transport sse <name> <url>

# 实际示例：连接到 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带有认证头的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

添加本地 Stdio 服务器

Stdio 服务器作为本地进程在机器上运行，适合需要直接系统访问或自定义脚本的工具。

# 基本语法
claude mcp add [options] <name> -- <command> [args...]

# 实际示例：添加 Airtable 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

选项顺序

所有选项（--transport、--env、--scope、--header）必须在服务器名称之前。--（双破折号）然后将服务器名称与传递给 MCP 服务器的命令和参数分隔开。

例如：

• claude mcp add --transport stdio myserver -- npx server → 运行 npx server
• claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 以环境变量 KEY=value 运行 python server.py --port 8080

这样可以防止 Claude 的标志与服务器的标志发生冲突。

管理服务器

配置完成后，我可以通过以下命令管理 MCP 服务器：

# 列出所有配置的服务器
claude mcp list

# 获取特定服务器的详细信息
claude mcp get github

# 移除服务器
claude mcp remove github

#（在 Claude Code 中）检查服务器状态
/mcp

常用 MCP 服务器

以下是一些常用的可以连接到 Claude Code 的 MCP 服务器：

使用第三方 MCP 服务器需自行承担风险——Anthropic 未验证所有这些服务器的正确性或安全性。确保信任你安装的 MCP 服务器。在使用可能获取不受信任内容的 MCP 服务器时要格外小心，因为这可能会使你面临提示注入风险。

MCP 配置作用域

MCP 服务器可以在三个不同的作用域级别进行配置，每个级别都有独特的管理服务器可访问性和共享的目的。

Local 作用域

Local 作用域服务器是默认的配置级别，存储在 ~/.claude.json 下的项目路径中。这些服务器仅属于我个人，仅在当前项目目录内工作时可访问。这个作用域适合个人开发服务器、实验性配置或包含不应共享的敏感凭证的服务器。

注意：MCP 的 “local 作用域” 术语与一般的 local 设置不同。MCP local 作用域服务器存储在 ~/.claude.json（你的主目录）中，而一般 local 设置使用 .claude/settings.local.json（在项目目录中）。

# 添加 local 作用域服务器（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 明确指定 local 作用域
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project 作用域

Project 作用域服务器通过在项目根目录存储 .mcp.json 文件来实现团队协作。该文件旨在签入版本控制，确保所有团队成员可以访问相同的 MCP 工具和服务。

# 添加 project 作用域服务器
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json 文件遵循标准化格式：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

出于安全原因，Claude Code 在使用来自 .mcp.json 文件的 project 作用域服务器之前会提示批准。如果需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令。

User 作用域

User 作用域服务器存储在 ~/.claude.json 中，提供跨项目可访问性，使我机器上所有项目都可以使用这些服务器，同时对我的用户账户保持私密。这个作用域适用于跨不同项目的个人实用工具、开发工具或经常使用的服务。

# 添加 user 作用域服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

选择合适的作用域

根据以下标准选择作用域：

• Local 作用域：个人服务器、实验性配置或特定于一个项目的敏感凭证
• Project 作用域：团队共享服务器、项目特定工具或协作所需的服务
• User 作用域：跨多个项目需要的个人实用工具、开发工具或经常使用的服务

MCP 服务器存储在哪里？

• User 和 local 作用域：~/.claude.json（在 mcpServers 字段中或项目路径下）
• Project 作用域：项目根目录中的 .mcp.json（签入源代码控制）
• Managed：系统目录中的 managed-mcp.json（见下文）

作用域层次和优先级

MCP 服务器配置遵循清晰的优先级层次。当多个作用域中存在同名服务器时，系统通过优先考虑 local 作用域服务器来解决冲突，其次是 project 作用域服务器，最后是 user 作用域服务器。这种设计确保了在需要时个人配置可以覆盖共享配置。

环境变量扩展

Claude Code 支持 .mcp.json 文件中的环境变量扩展，允许团队在保持机器特定路径和敏感值（如 API 密钥）的灵活性的同时共享配置。

支持的语法：

• ${VAR} - 扩展为环境变量 VAR 的值
• ${VAR:-default} - 如果设置了则扩展为 VAR，否则使用 default

扩展位置：

环境变量可以在以下位置扩展：

• command - 服务器可执行文件路径
• args - 命令行参数
• env - 传递给服务器的环境变量
• url - 对于 HTTP 服务器类型
• headers - 对于 HTTP 服务器认证

带变量扩展的示例：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

如果所需的环境变量未设置且没有默认值，Claude Code 将无法解析配置。

实战案例

案例 1：使用 Chrome DevTools MCP

Chrome DevTools MCP 服务器让我能够直接通过 Claude Code 分析网页性能和调试问题。

前提条件：

• Node.js v20.19 或更高版本
• Chrome 当前稳定版本

方法一：使用 CLI 命令添加

# 添加 Chrome DevTools MCP 服务器到 user 作用域
claude mcp add --scope user chrome-devtools -- npx chrome-devtools-mcp@latest

# 重启 Claude Code 使配置生效

方法二：通过 settings.json 配置

如果更喜欢手动配置，可以直接编辑 settings.json 文件：

# 编辑用户配置文件
vim ~/.claude.json

在 mcpServers 部分添加以下配置：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "env": {}
    }
  }
}

如果不想收集使用统计，可以添加环境变量：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-usage-statistics"
      ],
      "env": {}
    }
  }
}

使用示例

# 重启 Claude Code 使配置生效后，可以这样使用：

# 分析网页性能
> "检查 https://developers.chrome.com 的性能表现"

# 调试页面问题
> "分析我本地运行在 localhost:3000 的页面，找出性能瓶颈"

# 检查网络请求
> "获取 https://example.com 页面加载时的所有网络请求"

配置说明：

• CLI 命令会自动将配置写入 ~/.claude.json（user 作用域）
• 浏览器配置文件存储在 $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
• 使用 --no-usage-statistics 标志可以禁用 Google 的使用统计收集

案例 2：连接 GitHub 进行代码审查

# 添加 GitHub MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 在 Claude Code 中，如果需要则进行认证
> /mcp
# 选择 GitHub 的 "Authenticate"

# 现在可以请求 Claude 与 GitHub 交互
> "审查 PR #456 并提出改进建议"
> "为我们刚刚发现的 Bug 创建一个新 issue"
> "显示分配给我的所有开放 PR"

案例 3：查询 PostgreSQL 数据库

# 添加带有连接字符串的数据库服务器
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

# 自然地查询数据库
> "我们这个月的总收入是多少？"
> "显示 orders 表的 schema"
> "找到 90 天内没有购买的客户"

安全提示：对于生产数据库，我通常配置一个只读账户 (Read-only User) 给 MCP Server，以防止 AI 意外执行 DROP TABLE 等毁灭性操作。

案例 4：使用 MCP 资源

MCP 服务器可以暴露我可以使用 @ 提及来引用的资源，类似于引用文件的方式。

# 引用特定资源
> 可以分析 @github:issue://123 并建议修复方案吗？

> 请查看 @docs:file://api/authentication 的 API 文档

# 在单个提示中引用多个资源
> 比较 @postgres:schema://users 和 @docs:file://database/user-model

MCP 提示作为命令

MCP 服务器可以暴露在 Claude Code 中可作为命令使用的提示。

执行 MCP 提示

# 在提示中发现可用的命令
> /

# 无参数执行提示
> /mcp__github__list_prs

# 带参数执行提示
> /mcp__github__pr_review 456

> /mcp__jira__create_issue "登录流程中的 Bug" 高

• MCP 提示从连接的服务器动态发现
• 参数根据提示的已定义参数解析
• 提示结果直接注入到对话中
• 服务器和提示名称已规范化（空格变为下划线）

认证远程 MCP 服务器

许多基于云的 MCP 服务器需要认证。Claude Code 支持 OAuth 2.0 进行安全连接。

# 添加需要认证的服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 在 Claude Code 中使用 /mcp 命令
> /mcp

# 在浏览器中按照步骤登录

• 认证令牌安全存储并自动刷新
• 使用 /mcp 菜单中的 “清除认证” 来撤销访问
• 如果你的浏览器没有自动打开，复制提供的 URL
• OAuth 认证适用于 HTTP 服务器

使用预配置的 OAuth 凭据

某些 MCP 服务器不支持自动 OAuth 设置。如果看到类似 “不兼容的认证服务器：不支持动态客户端注册” 的错误，则服务器需要预配置的凭据。首先通过服务器的开发者门户注册一个 OAuth 应用，然后在添加服务器时提供凭据。

# 使用 --client-id 传递应用的客户端 ID
# --client-secret 标志提示输入带有掩码输入的密钥
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

MCP 输出限制和警告

当 MCP 工具产生大型输出时，Claude Code 帮助管理 token 使用以防止使对话上下文不堪重负：

• 输出警告阈值：当任何 MCP 工具输出超过 10,000 个 token 时，Claude Code 显示警告
• 可配置限制：可以使用 MAX_MCP_OUTPUT_TOKENS 环境变量调整允许的最大 MCP 输出 token
• 默认限制：默认最大值为 25,000 个 token

# 为 MCP 工具输出设置更高的限制
export MAX_MCP_OUTPUT_TOKENS=50000
claude

这对于使用以下 MCP 服务器特别有用：

• 查询大型数据集或数据库
• 生成详细报告或文档
• 处理大量日志文件或调试信息

动态工具更新

Claude Code 支持 MCP list_changed 通知，允许 MCP 服务器动态更新其可用的工具、提示和资源，而无需断开并重新连接。当 MCP 服务器发送 list_changed 通知时，Claude Code 自动从该服务器刷新可用的功能。

使用 JSON 配置添加 MCP 服务器

如果我有 MCP 服务器的 JSON 配置，可以直接添加：

# 基本语法
claude mcp add-json <name> '<json>'

# 示例：添加带有 JSON 配置的 HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 示例：添加带有 JSON 配置的 stdio 服务器
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 示例：添加带有预配置 OAuth 凭据的 HTTP 服务器
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

从 Claude Desktop 导入 MCP 服务器

如果已经在 Claude Desktop 中配置了 MCP 服务器，可以导入它们：

# 基本语法
claude mcp add-from-claude-desktop

这将显示一个交互式对话框，允许选择要导入的服务器。

• 此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上可用
• 它从这些平台上的标准位置读取 Claude Desktop 配置文件
• 使用 --scope user 标志将服务器添加到用户配置
• 导入的服务器将与 Claude Desktop 中的名称相同

实战心得

在使用 MCP 的过程中，我深刻体会到：

1. 去中心化：我不需要等待 Anthropic 官方支持每一个工具。只要有 API，我就可以写一个 MCP Server 把它接进来。
2. 上下文动态化：以前我需要手动把文件贴给 Claude，现在它通过 Resource 订阅，能在文件/数据变更时自动感知。
3. 安全性隔离：MCP Server 运行在独立的进程中。即使 AI 试图越权，它也被限制在 MCP Server 定义的工具集内，无法触碰操作系统的其他部分。
4. 跨项目一致性：通过 project 作用域，我可以为团队配置统一的 MCP 工具集，确保所有人使用相同的工具和配置。
5. 灵活作用域：local、project 和 user 三个作用域让我可以根据需求选择最合适的配置级别，平衡个人使用、团队协作和跨项目共享的需求。

结语

MCP Server 是 Claude Code 从”文本处理工具”进化为”全能数字助手”的关键拼图。通过连接 GitHub、数据库和各类内部系统，我让 AI 真正融入了我的研发工作流闭环。

它不再是一个孤立的聊天窗口，而是成为了系统的一部分。

更多资源：

• MCP 官方文档
• GitHub 上的 MCP 服务器仓库

---

下一篇预告：Claude Code(九)Plugins：扩展功能的无限可能