Claude Code 配置 MCP 教程（命令行与JSON）

浏览：3次阅读

Claude Code 配置 MCP 最简单的做法是一条 claude mcp add 命令：远程服务用 --transport http 加地址，本地服务用 -- 接启动命令，再用 /mcp 检查连接状态。下面按官方文档把命令行、JSON 两种配置方法和常见报错讲清楚。

图片来源：Model Context Protocol 官网

MCP（Model Context Protocol，模型上下文协议）是一个开源的 AI 工具接入标准。Claude Code 通过 MCP 服务器连接外部工具、数据库和 API，连上之后就不用再把 Issue、监控数据、表结构手动复制进对话，Claude 可以直接读取并操作这些系统。官方文档举的例子包括：根据 Jira 任务写代码并在 GitHub 提 PR、查询 PostgreSQL 数据库、读取 Sentry 监控数据、按 Figma 设计稿改页面等。

MCP 架构示意：左边是 Claude Code 等 AI 应用，右边是数据库、开发工具和办公工具。图片来源：modelcontextprotocol.io

开始之前请先装好 Claude Code 并能正常对话。还没装的可以看 Claude Code Windows 原生安装教程；用第三方 API 的朋友可以先看 Claude Code 接入第三方 API 配置教程。MCP 配置和你用官方账号还是第三方 API 无关，两种方式都能用。

MCP 服务器分三种连接方式，先看服务商文档给的是网址还是启动命令，再选对应写法。

官方推荐优先使用 HTTP 方式连接远程 MCP 服务。基本语法和示例：

# 基本语法
claude mcp add --transport http < 名称 > < 地址 >

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

# 需要 Token 的服务，用 --header 传认证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

只提供 SSE 地址的老服务，也可以用同样的 --transport http 命令添加，新版 Claude Code（v2.1.265 及以上）会先试 HTTP，不行再自动切到 SSE。版本较旧时改成 --transport sse。SSE 方式官方已标记为弃用。

本地服务器在你电脑上作为进程运行，适合需要访问本机文件或运行自定义脚本的工具。注意中间的双横线 --：它前面是 Claude Code 自己的参数，后面是启动服务器的命令，原样传过去。

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

# 示例：添加 Airtable，并通过 --env 传入密钥
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

一个容易踩的坑：--env 后面紧跟服务器名称时，名称会被当成另一个环境变量而报错，所以要像上面一样在两者之间放一个别的选项，比如 --transport stdio。

用 -s 或 --scope 指定配置存在哪里：

local（默认）：只在当前项目生效，只有你自己能用，存在 ~/.claude.json 里该项目的条目下。适合放带密钥的个人配置。
project：写入项目根目录的 .mcp.json，可以提交到 Git 和团队共享。
user：存在 ~/.claude.json，你电脑上的所有项目都能用。

同名服务器在多个作用域都有定义时，优先级是 local > project > user，使用优先级最高的那一份完整配置，字段不会合并。

# 所有项目通用的服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

claude mcp list          # 列出所有服务器和连接状态
claude mcp get notion    # 查看某个服务器详情
claude mcp remove notion # 删除服务器
/mcp                     # 在 Claude Code 会话里查看状态、登录 OAuth

claude mcp list 会在每个服务器旁显示状态，比如 ✔ Connected（已连接）、! Needs authentication（需要登录）、✘ Failed to connect（连接失败）。需要 OAuth 登录的服务（比如 Sentry、Notion），在会话里输入 /mcp 按浏览器提示登录即可；也可以在终端运行 claude mcp login 名称 。

Claude Code 终端界面（官方演示动图截帧）。图片来源：anthropics/claude-code GitHub 仓库

很多 MCP 服务的说明是给 Claude Desktop 或 Cursor 写的，只给了一段 mcpServers JSON。这时用 claude mcp add-json，注意只传 mcpServers 里面那个对象，不要连外层一起传。比如说明里是：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

在 Claude Code 里对应的命令是：

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

想和团队共享，就直接在项目根目录建 .mcp.json，格式如下。远程服务一定要写 "type"：

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

.mcp.json 里可以用 ${VAR} 或 ${VAR:- 默认值} 引用环境变量，这样密钥不用写死在文件里。另外，如果你在 Claude Desktop 里已经配好了服务器，macOS 和 WSL 下可以运行 claude mcp add-from-claude-desktop 一键导入。

JSON 里写了 url 却没写 type，Claude Code 会把它当成本地 stdio 服务而跳过。解决：按服务实际协议加上 "type": "http"（或 "sse"、"ws"）。streamable-http 也会被识别为 http。

同一作用域下已经有同名服务器。先 claude mcp remove 名称 再重新添加，或者换一个名称。服务器名称只能包含字母、数字、连字符和下划线，workspace、computer-use 等内置名称也不能用。

这是项目 .mcp.json 里的服务器还没被你批准。在项目目录直接运行 claude，接受工作区信任提示并批准该服务器即可。想重置之前的批准选择，运行 claude mcp reset-project-choices。

先检查 Token 是否正确、有没有复制进多余的空格或换行（Claude Code 会提示 Leading or trailing whitespace in: headers.Authorization）。用第三方 API 的朋友特别注意：为了防止凭据泄露，远程服务的 url 和 headers 里引用 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、HTTPS_PROXY 这类变量时会被当成空值，服务端收不到 Token 就返回 401。解决办法是把密钥放进你自己命名的变量（比如 MY_MCP_TOKEN）再引用。

启动慢的服务可以加大启动超时，例如 MCP_TIMEOUT=10000 claude（10 秒）。如果服务器自己的参数（如 --port）被 Claude Code 当成未知选项，多半是漏了 -- 分隔符。

MCP 工具输出超过 10000 token 时会出现警告，默认上限 25000 token。确实需要更长输出时，设置 MAX_MCP_OUTPUT_TOKENS=50000 这样的环境变量。

官方文档说明，claude.ai 的连接器只在用 claude.ai 订阅账号登录时加载；设置了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 时不会加载。这种情况下用 claude mcp add 在本地添加服务器即可，效果一样。想一次把第三方 API 和 Claude Code 配好，也可以参考 Claude Code/Codex 一条命令配置教程。

在 /mcp 面板里把它关掉，配置会保留，之后可以再打开。

官方提醒：只连接你信任的服务器，会抓取外部内容的服务器有提示词注入风险。数据库类服务建议用只读账号连接。

信息来源：Claude Code 官方文档：Connect Claude Code to tools via MCP；Model Context Protocol 官方介绍。核实时间：2026-10-30。

正文完