Claude Code MCP 服务器配置指南

通过 MCP（Model Context Protocol）连接外部工具和数据源，让 Claude Code 的能力无限扩展。

什么是 MCP？

MCP（Model Context Protocol）是一个标准协议，让 AI 系统能够连接外部工具、API 和数据源。通过配置 MCP 服务器，Claude Code 可以：

• 🔧 操作 GitHub、Jira、Slack 等服务
• 📊 查询数据库
• 🌐 调用内部 API
• 📁 访问特殊数据源
• 🔌 使用任何符合 MCP 协议的工具

配置位置

MCP 服务器可以在以下位置配置：

通过命令添加 MCP 服务器

除了手动维护配置文件，也可以用 claude mcp add <name> <commandOrUrl> [args...] 直接把服务器写入配置。该命令会根据 --scope 将内容保存到不同文件：

• --scope project → 写入项目根目录的 .mcp.json
• --scope local（默认）→ 写入 .claude/settings.local.json
• --scope user → 写入 ~/.claude/settings.json

首次添加的服务器依然会触发与文件配置相同的信任审批；批准结果记录在 .claude/settings.local.json 中。

操作流程

1. 选择作用域：使用 --scope local|user|project 决定谁能看到该服务器，默认为当前项目本机（local）。
2. 确定传输方式：--transport stdio|http|sse，默认 stdio。如果命令像 URL 却没指定传输，CLI 会警告以免把远程服务器当成本地进程。
3. 补充认证信息：
   • -e/--env KEY=value 仅适用于 stdio 服务器，为子进程注入环境变量，可用多次。
   • -H/--header "K: V" 用于 HTTP/SSE 服务器附加请求头。
   • --client-id、--client-secret、--callback-port 仅对 HTTP/SSE 生效；--client-secret 会提示输入密钥并安全存入 .claude/settings.local.json（或对应 scope 的设置文件）。
   • 需要基于 SEP-990 的 XAA 登录时，先运行 claude mcp xaa setup，然后为 HTTP/SSE 命令附加 --xaa --client-id ... --client-secret。
4. 运行命令并确认输出：CLI 会打印写入的配置路径（如 .mcp.json），若服务器配置与策略冲突会立即报错。
5. （可选）验证连接：在 Claude Code 中执行 /mcp 查看新服务器是否已就绪。

使用 claude mcp add --help 可以查看全部标志位和更详细的说明。

行为差异

• stdio：将 <commandOrUrl> 当作可执行文件，[args...] 通过 -- 传递。OAuth、headers、--xaa 在 stdio 模式下会被忽略。若误把 URL 写在这里，命令会输出纠正提示。
• HTTP：需要显式 --transport http 并传入服务器 URL，可选 headers、OAuth、XAA。适合一次性请求/响应的 REST 样式 MCP。
• SSE：以 --transport sse 连接长轮询/Server-Sent Events 端点。和 HTTP 一样支持 headers/OAuth/XAA，但更适合持续流式能力。

命令示例

1. stdio 服务器（带环境变量和子命令）

claude mcp add -s project -e API_KEY=$INTERNAL_KEY filesystem -- npx -y @anthropic/mcp-filesystem /srv/shared

2. HTTP 服务器（自定义 Header）

claude mcp add --scope user --transport http corridor https://app.corridor.dev/api/mcp \
  -H "Authorization: Bearer $CORRIDOR_TOKEN" \
  -H "X-Tenant: ops"

3. SSE 服务器（OAuth + 回调端口）

claude mcp add --transport sse sentry https://mcp.sentry.dev/mcp \
  --client-id $SENTRY_CLIENT_ID \
  --client-secret \
  --callback-port 38910

上述命令在写入配置后，会提示首次连接仍需在 Claude 中批准，与直接编辑 .mcp.json 的审批流程一致。密钥和 Token 一律保存在本地设置文件中，不会写入版本控制。完成添加后，可随时运行 /mcp 检查状态，并通过 claude mcp add --help 了解更多进阶选项。

.mcp.json 格式

项目根目录下的 .mcp.json 是最常用的配置方式：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

服务器类型

1. stdio 服务器（本地进程）

最常见的类型，通过 stdin/stdout 通信：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./mcp-server/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

2. npx 远程包

直接从 npm 安装并运行：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/allowed/dir"]
    }
  }
}

3. SSE/Streamable HTTP 服务器（远程）

连接远程 MCP 服务器：

{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

常用 MCP 服务器

GitHub

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

功能：创建 Issue、PR、查看代码、管理仓库等。

文件系统（扩展访问）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "@anthropic/mcp-filesystem",
        "/Users/me/documents",
        "/Users/me/downloads"
      ]
    }
  }
}

让 Claude 访问项目目录之外的文件。

PostgreSQL 数据库

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Web 搜索

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

自定义内部 API

{
  "mcpServers": {
    "internal-api": {
      "command": "python3",
      "args": ["-m", "my_company.mcp_server"],
      "env": {
        "API_ENDPOINT": "https://api.internal.company.com",
        "API_TOKEN": "${INTERNAL_API_TOKEN}"
      }
    }
  }
}

在 Agent 中配置 MCP

Agent 可以声明自己需要的 MCP 服务器：

引用已有服务器

---
name: devops-agent
description: DevOps 运维 Agent
mcpServers:
  - github
  - slack
---

内联定义服务器

---
name: data-agent
description: 数据分析 Agent
mcpServers:
  - name: analytics-db
    command: npx
    args: ["-y", "@anthropic/mcp-postgres"]
    env:
      DATABASE_URL: "${ANALYTICS_DB_URL}"
---

要求必须有特定 MCP

---
name: jira-agent
description: Jira 项目管理 Agent
requiredMcpServers:
  - jira
---

设置 requiredMcpServers 后，如果对应的 MCP 服务器未配置，该 Agent 将不可用。

审批与安全

首次使用审批

项目 .mcp.json 中的 MCP 服务器首次使用时会弹窗询问用户是否信任。批准后记录在：

// .claude/settings.local.json
{
  "enabledMcpjsonServers": ["github", "slack"],
  "disabledMcpjsonServers": ["untrusted-server"]
}

自动批准所有项目 MCP

// .claude/settings.json 或 settings.local.json
{
  "enableAllProjectMcpServers": true
}

⚠️ 仅在信任项目中的所有 MCP 定义时使用。

企业白名单

管理员可以限制允许使用的 MCP 服务器：

// managed-settings.json
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-api" },
    { "serverCommand": ["npx", "-y", "@company/approved-mcp"] },
    { "serverUrl": "https://*.company.com/*" }
  ]
}

匹配方式（三选一）：

• serverName — 按名称匹配
• serverCommand — 按命令精确匹配
• serverUrl — 按 URL 模式匹配（支持通配符 *）

企业黑名单

{
  "deniedMcpServers": [
    { "serverName": "dangerous-tool" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

黑名单优先级高于白名单。

仅使用管理员白名单

{
  "allowManagedMcpServersOnly": true
}

设置后，用户仍可添加自己的 MCP 服务器，但只有管理员定义的白名单控制哪些能用。

环境变量

MCP 配置中的环境变量使用 ${VAR_NAME} 语法引用运行时环境变量：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "DB_HOST": "${DB_HOST:-localhost}",
        "DEBUG": "true"
      }
    }
  }
}

也可以在 settings.json 的 env 字段中预设环境变量：

{
  "env": {
    "GITHUB_TOKEN": "ghp_xxxx",
    "SLACK_BOT_TOKEN": "xoxb-xxxx"
  }
}

沙箱中的 MCP

当沙箱启用时，MCP 服务器的网络访问也受沙箱限制：

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["api.github.com", "slack.com"]
    }
  }
}

确保 MCP 服务器需要访问的域名在白名单中。

调试与排查

查看 MCP 服务器状态

在 Claude Code 中使用 /mcp 命令查看当前已连接的 MCP 服务器。

常见问题

最佳实践

1. 敏感信息用环境变量 — 不要在 .mcp.json 中硬编码 Token
2. .mcp.json 提交到 Git — 团队共享 MCP 配置
3. Token 放在 settings.local.json 的 env — 个人的不提交
4. 企业环境用白名单 — allowedMcpServers 防止不受控的外部连接
5. Agent 声明 requiredMcpServers — 确保依赖的服务器可用
6. 沙箱 + MCP 一起用 — 安全且功能丰富