古法编程

Appearance

MCP：连接外部工具 ​

为 Claude Code 配置 MCP (Model Context Protocol) 是扩展其能力、连接外部工具和数据源的关键步骤。您可以通过 claude mcp add 命令轻松配置 MCP 服务器，支持 HTTP、stdio 等多种传输方式。无论是配置 MCP server 连接云端服务，还是通过 MCP JSON 文件进行项目级管理，本文都提供了详细指南。具体来说，配置 claude code mcp 工具主要涉及服务器添加、认证设置（如 OAuth）和作用域管理（local、project、user）。对于需要精细控制的场景，您还可以直接编辑 .mcp.json 配置文件，使用环境变量占位符增强安全性。掌握如何给 Claude Code 配置 MCP，能显著提升其与数据库、API、GitHub 等上百种工具的协同效率。

Claude Code 通过 Model Context Protocol (MCP) 连接外部工具和数据源。MCP 是一个开源协议，为 AI 工具集成提供标准接口，让你可以把 Claude Code 接入数据库、API、监控系统等上百种工具。

能做什么 ​

接入 MCP 服务器后，你可以这样使用 Claude Code：

实现 JIRA ENG-4521 中描述的功能，并在 GitHub 创建 PR
检查 Sentry 和 Statsig，查看 ENG-4521 功能的使用情况
根据 PostgreSQL 数据库，找出使用过该功能的 10 个随机用户的邮件地址
根据 Figma 新设计稿更新标准邮件模板
给这 10 个用户创建 Gmail 草稿，邀请他们参与新功能的反馈

MCP 服务器还可以作为 Channel，把外部消息推入你的会话——让 Claude 在你不在时也能响应 Telegram 消息、Discord 聊天或 Webhook 事件。

热门 MCP 服务器 ​

以下是一些常用的 MCP 服务器，可以一行命令接入：

服务添加命令
Linear（项目管理）claude mcp add --transport http linear https://mcp.linear.app/mcp
Notion（知识库）claude mcp add --transport http notion https://mcp.notion.com/mcp
Jira & Confluenceclaude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp
Figma（设计稿）claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp
Sentry（错误监控）claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Supabase（数据库）claude mcp add --transport http supabase https://mcp.supabase.com/mcp
Vercel（部署）claude mcp add --transport http vercel https://mcp.vercel.com
GitHub Copilotclaude mcp add --transport http github https://api.githubcopilot.com/mcp/
Stripe（支付）claude mcp add --transport http stripe https://mcp.stripe.com
Exa（网页搜索）claude mcp add --transport http exa https://mcp.exa.ai/mcp

添加 MCP 服务器 ​

方式一：HTTP 服务器（推荐） ​

HTTP 是最广泛支持的传输方式，适合连接云端服务。

bash
# 基本语法
claude mcp add --transport http <名称> <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 传输已废弃，请使用 HTTP 方式。

bash
claude mcp add --transport sse asana https://mcp.asana.com/sse

方式三：本地 stdio 服务器 ​

本地进程方式，适合需要直接系统访问或自定义脚本的工具。

bash
# 基本语法
claude mcp add [options] <名称> -- <命令> [参数...]

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

重要：--transport、--env、--scope、--header 等选项必须放在服务器名称前面，--（双破折号）后面才是传给 MCP 服务器的命令和参数。

Windows 用户注意：原生 Windows（非 WSL）下，使用 npx 的本地 MCP 服务器需要加 cmd /c 包装：

bash
# 正确写法
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

管理服务器 ​

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

# 查看特定服务器详情
claude mcp get github

# 删除服务器
claude mcp remove github

# 在 Claude Code 内查看服务器状态
/mcp

配置作用域 ​

每个 MCP 服务器都可以指定存储位置（--scope）：

作用域存储位置适用场景
local（默认）~/.claude.json 下项目路径仅当前项目，不与他人共享
project项目根目录的 .mcp.json与团队共享，提交到 git
user~/.claude.json跨项目使用，个人专属
bash
# 项目范围（可以提交到 git 共享给团队）
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 用户范围（跨所有项目可用）
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

生成的 .mcp.json 文件示例：

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

安全提示：加载项目 .mcp.json 中的服务器前，Claude Code 会要求你确认。用 claude mcp reset-project-choices 重置审批记录。

环境变量扩展 ​

.mcp.json 支持环境变量占位符：

json
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
  • ${VAR} — 展开为环境变量值
  • ${VAR:-default} — 未设置时使用默认值

OAuth 认证 ​

许多云端 MCP 服务器需要 OAuth 2.0 认证：

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

认证令牌会安全存储并自动刷新。在 /mcp 菜单中选"Clear authentication"可以撤销访问。

固定回调端口 ​

bash
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

从 JSON 添加服务器 ​

bash
# HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdio 服务器
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

从 Claude Desktop 导入 ​

bash
claude mcp add-from-claude-desktop

仅支持 macOS 和 WSL。同名服务器会添加数字后缀（如 server_1）。

实战示例 ​

连接 Sentry 监控错误 ​

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

认证后使用：

最近 24 小时最常见的错误是什么？
给我看看错误 ID abc123 的调用栈
哪次部署引入了这些新错误？

连接 GitHub 做代码审查 ​

bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
审查 PR #456 并提出改进建议
为刚发现的 bug 创建新 issue
列出分配给我的所有开放 PR

连接 PostgreSQL 数据库 ​

bash
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
本月总收入是多少？
显示 orders 表的结构
找出 90 天内没有购买记录的用户

使用 MCP 资源 ​

MCP 服务器可以暴露可引用的资源，用 @ 语法引用：

分析 @github:issue://123 并建议修复方案
查阅 @docs:file://api/authentication 中的 API 文档
对比 @postgres:schema://users 和 @docs:file://database/user-model

使用 MCP 提示词作为命令 ​

MCP 服务器暴露的 prompt 可以变成 / 命令：

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "登录流程 bug" high

MCP 工具搜索（大量工具时） ​

MCP 工具多时，工具定义会占用大量上下文窗口。MCP Tool Search 在需要时按需加载工具。

当 MCP 工具描述超过上下文窗口的 10% 时自动启用。

ENABLE_TOOL_SEARCH 值行为
未设置（默认）自动启用，第三方 Base URL 时禁用
true始终启用
auto超过 10% 阈值时激活
auto:5超过 5% 时激活
false禁用，始终预加载所有工具
bash
# 设置 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

将 Claude Code 作为 MCP 服务器 ​

Claude Code 本身也可以作为 MCP 服务器运行：

bash
claude mcp serve

在 Claude Desktop 的 claude_desktop_config.json 中配置：

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

企业级管理 ​

方式一：托管 MCP 配置（独占控制） ​

部署到系统目录，用户无法修改：

系统路径
macOS/Library/Application Support/ClaudeCode/managed-mcp.json
Linux/WSL/etc/claude-code/managed-mcp.json
WindowsC:\Program Files\ClaudeCode\managed-mcp.json
json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}

方式二：基于策略的控制（白名单/黑名单） ​

json
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}
  • allowedMcpServers: []（空数组）= 完全禁止所有 MCP 服务器
  • allowedMcpServers 未定义 = 不限制
  • 黑名单（deniedMcpServers）优先于白名单

输出限制 ​

设置默认值
警告阈值10,000 tokens
最大输出25,000 tokens
bash
# 增加输出上限
export MAX_MCP_OUTPUT_TOKENS=50000
claude

故障排查题 ​

服务器连接失败

  • 检查 URL 和认证凭据是否正确
  • 运行 /mcp 查看服务器状态和错误信息
  • 使用 MCP_TIMEOUT 环境变量增加超时时间：MCP_TIMEOUT=10000 claude

Windows 下 "Connection closed" 错误

  • 本地 stdio 服务器需要 cmd /c 包装：-- cmd /c npx -y @some/package

工具太多导致上下文溢出

  • 启用 MCP Tool Search（默认已开启），或设置 ENABLE_TOOL_SEARCH=true

相关资源 ​

常见问题 ​

Q: 如何为 Claude Code 配置 MCP 服务器？

使用 claude mcp add 命令即可配置。对于 HTTP 服务器，命令为 claude mcp add --transport http <名称> <URL>；对于本地工具，使用 --transport stdio 并指定命令。配置时可使用 --scope 参数定义作用范围（如 project 用于团队共享）。

Q: Claude Code 配置 MCP 时，HTTP 和 stdio 方式有什么区别？

HTTP 方式用于连接云端服务（如 Notion、Sentry），是最推荐的方式；stdio 方式用于运行本地进程或脚本，适合需要直接系统访问的工具。注意，SSE 传输方式已废弃。

Q: 如何通过 JSON 文件为 Claude Code 配置 MCP？

有两种方法：1) 使用 claude mcp add --scope project 命令会在项目根目录生成 .mcp.json 文件；2) 使用 claude mcp add-json 命令直接添加 JSON 配置。在 JSON 文件中，您可以使用 ${ENV_VAR} 语法引用环境变量。

Q: 配置 Claude Code MCP 时，local、project、user 作用域有何不同？

local（默认）仅当前项目可用；project 配置保存在项目 .mcp.json 中，可提交至 Git 与团队共享；user 配置保存在用户目录，所有项目均可使用。应根据协作需求选择合适的作用域。

Q: 为 Claude Code 配置 MCP 工具后如何管理和验证？

使用 claude mcp list 查看所有服务器，claude mcp get <名称> 查看详情。在 Claude Code 界面中输入 /mcp 可以查看服务器状态、进行 OAuth 认证或清除认证。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策