Claude Code MCP 完全指南：连接 AI 与外部世界

概述

本文档介绍如何使用 Model Context Protocol (MCP)（AI 工具集成的开源标准）将 Claude Code 连接到数百个外部工具和数据源。MCP 服务器为 Claude Code 提供对工具、数据库和 API 的访问能力，让 Claude 能够直接与外部系统交互，自动化复杂工作流。

---

什么是 MCP

Model Context Protocol (MCP) 是用于 AI 工具集成的开源标准。连接 MCP 服务器后，Claude Code 可以：

• 从问题跟踪器实现功能：直接根据 JIRA 描述开发功能并创建 PR
• 分析监控数据：同时检查 Sentry 和 Statsig 数据分析使用情况
• 查询数据库：自然语言查询 PostgreSQL 等数据库获取结果
• 集成设计：根据 Figma 设计更新代码
• 自动化工作流：创建 Gmail 草稿、发送邀请等
• 响应外部事件：MCP 服务器可作为频道推送消息，让 Claude 响应 Telegram、Discord、webhook 事件

---

安装 MCP 服务器

MCP 服务器支持三种配置方式：

选项 1：添加远程 HTTP 服务器（推荐）

HTTP 是连接远程 MCP 服务器的推荐传输方式，被云服务广泛支持。

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

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

# 带有身份验证标头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

选项 2：添加远程 SSE 服务器（已弃用）

SSE (Server-Sent Events) 传输已弃用，推荐使用 HTTP。

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

选项 3：添加本地 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 list

# 获取特定服务器详细信息
claude mcp get <server-name>

# 删除服务器
claude mcp remove <server-name>

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

有用的提示

• --scope 指定配置存储位置：
  • local（默认）：仅当前项目可用（存储在 ~/.claude.json）
  • project：通过 .mcp.json 在项目中共享
  • user：所有项目可用（存储在 ~/.claude.json）
• 使用 --env 设置环境变量
• MCP_TIMEOUT=10000 配置 MCP 服务器启动超时
• MAX_MCP_OUTPUT_TOKENS=50000 增加 MCP 输出令牌限制（默认 10,000 警告，25,000 最大）
• OAuth 认证通过 /mcp 命令在浏览器中完成

Windows 注意：使用 npx 的本地 MCP 服务器需要 cmd /c 包装器：

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

---

MCP 安装范围

MCP 服务器可以在三个范围级别配置：

范围	存储位置	使用场景
本地 (local)	~/.claude.json	个人开发、实验配置、敏感凭据
项目 (project)	.mcp.json（项目根目录）	团队共享、协作、项目特定工具
用户 (user)	~/.claude.json	跨项目个人工具、常用服务

优先级

当同名服务器存在于多个范围时：本地范围 > 项目范围 > 用户范围。个人配置可以覆盖共享配置。

项目范围 .mcp.json 格式

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

环境变量扩展

Claude Code 支持 .mcp.json 中的环境变量扩展：

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

支持语法：${VAR} 和 ${VAR:-default}。

---

身份验证

许多基于云的 MCP 服务器需要身份验证，Claude Code 原生支持 OAuth 2.0。

基础 OAuth 流程

1. 添加服务器：claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. 在 Claude Code 运行 /mcp
3. 在浏览器中完成登录

预配置 OAuth 凭据

某些服务器需要预配置的 OAuth 应用凭据：

# 使用 claude mcp add
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

客户端密钥安全存储在系统钥匙串中，不在配置中明文保存。

自定义身份验证 - 动态标头

对于非 OAuth 身份验证方案，可以使用 headersHelper 在连接时生成请求标头：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

命令必须输出 JSON 对象格式的标头，每次连接时都会重新运行。

---

插件提供的 MCP 服务器

插件可以捆绑 MCP 服务器，启用插件时自动提供集成：

• 插件在 .mcp.json 或 plugin.json 中定义 MCP 服务器
• 启用插件时自动连接，禁用时断开（/reload-plugins 刷新）
• 支持 ${CLAUDE_PLUGIN_ROOT} 和 ${CLAUDE_PLUGIN_DATA} 变量
• 优势：捆绑分发、自动设置、团队一致性

示例插件配置：

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

---

实际示例

示例：使用 Sentry 监控错误

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

然后：

过去 24 小时内最常见的错误是什么？
显示错误 ID abc123 的堆栈跟踪
哪个部署引入了这些新错误？

示例：连接 GitHub 进行代码审查

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

然后：

审查 PR #456 并建议改进
为刚发现的错误创建新问题
显示分配给我的所有开放 PR

示例：查询 PostgreSQL 数据库

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

然后：

本月我们的总收入是多少？
显示订单表的架构
查找 90 天内未进行购买的客户

---

导入和同步

从 Claude Desktop 导入

claude mcp add-from-claude-desktop

交互式选择要导入的服务器。仅在 macOS 和 WSL 上有效。

从 Claude.ai 同步

如果已登录 Claude.ai 帐户，您在 claude.ai/settings/co… 中添加的 MCP 服务器会自动在 Claude Code 中可用，可通过 /mcp 查看管理。

禁用：ENABLE_CLAUDEAI_MCP_SERVERS=false claude

---

将 Claude Code 用作 MCP 服务器

您可以将 Claude Code 本身作为 MCP 服务器供其他应用连接：

# 启动 Claude 作为 stdio MCP 服务器
claude mcp serve

在 Claude Desktop 的配置中使用：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

注意：需要提供 claude 可执行文件的完整路径（使用 which claude 查找）。此服务器向 MCP 客户端公开 Claude Code 的工具（查看、编辑、LS 等）。

---

MCP 资源

MCP 服务器可以公开资源，使用 @ 提及引用：

1. 键入 @ 查看所有可用资源（和文件一起出现在自动完成菜单）
2. 使用格式 @server:protocol://resource/path 引用：

Can you analyze @github:issue://123 and suggest a fix?
Please review the API documentation at @docs:file://api/authentication

支持在单个提示中引用多个资源。

---

工具搜索

工具搜索通过延迟工具定义保持 MCP 上下文使用低，默认启用：

• 仅工具名称在会话启动时加载
• Claude 需要时才动态发现相关工具
• 只有实际使用的工具才进入上下文
• 添加更多服务器对上下文窗口影响最小

配置工具搜索

使用 ENABLE_TOOL_SEARCH 环境变量：

值	行为
（未设置）	默认：所有工具延迟按需加载
true	强制延迟，即使使用代理
auto	阈值模式：适合上下文 10% 则预加载，否则延迟
auto:N	自定义百分比阈值，例如 auto:5
false	禁用，所有工具预先加载

# 自定义 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

需要支持 tool_reference 块的模型：Sonnet 4+、Opus 4+。Haiku 不支持。

对于 MCP 服务器作者：添加清晰的服务器说明描述工具处理的任务类别，帮助 Claude 在需要时搜索到你的工具。

---

MCP 提示作为命令

MCP 服务器可以公开提示，在 Claude Code 中作为命令可用：

• 格式：/mcp__servername__promptname
• 参数通过空格分隔传递：/mcp__jira__create_issue "Bug in login flow" high
• 结果直接注入对话

---

托管 MCP 配置（企业）

对于需要集中控制的组织，支持两种方式：

选项 1：managed-mcp.json 独占控制

部署固定的 MCP 服务器集，用户无法修改或扩展：

• 系统级部署路径：
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux/WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\Program Files\ClaudeCode\managed-mcp.json
• 格式与 .mcp.json 相同
• 用户无法添加其他服务器

选项 2：基于策略的允许列表/拒绝列表

允许用户添加自己的服务器，但通过允许列表/拒绝列表限制：

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

限制方式：每个条目可以按 serverName、serverCommand（精确匹配）或 serverUrl（支持 * 通配符）限制。

规则：拒绝列表优先级 > 允许列表；必须匹配允许列表中至少一个条目才能使用。

---

安全警告

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

---

核心要点

• MCP 是连接 Claude Code 到外部工具和数据源的开放标准，支持数百种集成
• 三种传输方式：HTTP（推荐远程）、SSE（已弃用）、stdio（本地进程）
• 三个配置范围：本地（个人）、项目（团队共享）、用户（跨项目个人）
• 原生 OAuth 支持：安全的云服务身份验证，令牌安全存储
• 工具搜索 默认启用，通过延迟加载保持上下文高效
• 企业支持：托管配置和基于策略的访问控制
• 您可以将 Claude Code 本身作为 MCP 服务器 供其他应用（如 Claude Desktop）连接