首页 / 教程

Claude Code MCP 服务器配置与常见报错排查

更新于 2026-10-22 · 内容依据官方文档整理，配置项可能随版本变化，请以官方最新文档为准。

MCP（Model Context Protocol）服务器给 Claude Code 提供额外的工具，比如搜索、数据库、浏览器。服务器分两类：本地 stdio（在你机器上启动一个进程，常见 npx、uvx、docker）和远程 HTTP（填一个 URL）。本站每个 MCP 详情页都根据官方注册表信息推导了一条 claude mcp add 命令。

1. 添加服务器

# 远程 HTTP 服务器
claude mcp add --transport http exa https://mcp.exa.ai/mcp

# 本地 stdio 服务器：-- 之后是启动命令，-e 传环境变量
claude mcp add my-server -e API_KEY=xxx -- npx -y some-mcp-package

# 共享给团队（写入项目根目录 .mcp.json）
claude mcp add --scope project my-server -- npx -y some-mcp-package

对 stdio 服务器，-- 用来分隔 Claude Code 自己的参数（--transport、--env、--scope）和服务器启动命令，-- 之后的内容原样传给服务器。--transport、--header 也可以简写为 -t、-H。

2. 三种作用域

作用域说明
local（默认）只对你自己、只在当前项目生效
project写入项目根目录 .mcp.json，提交后团队共享
user对你自己的所有项目生效

.mcp.json 的结构如下，支持 ${VAR} 引用环境变量，这样密钥不用写进仓库：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": { "API_KEY": "${API_KEY}" }
    }
  }
}

3. 查看状态

claude mcp list          # 列出并检查连接状态
claude mcp get <name>    # 查看单个服务器详情和报错
claude mcp remove <name> # 删除

会话中输入 /mcp 可以查看各服务器状态、完成 OAuth 登录、临时停用某个服务器。

4. 常见报错与处理

现象原因与处理
✘ Failed to connect服务器启动失败或 URL 不通。用 claude mcp get 名称 看 Issue: 行里的 HTTP 状态码和错误信息；本地服务器可以先在终端单独运行启动命令，看是否缺依赖（Node、Python/uv、Docker）。
! Needs authentication远程服务器需要 OAuth 登录，在会话里输入 /mcp 选中该服务器完成授权。
⏸ Pending approval项目 .mcp.json 里的服务器还没被你批准。在该目录交互式运行 claude，信任工作区并批准。克隆来的仓库不能自己批准自己的服务器。
⊘ Disabled for this project在 /mcp 面板里重新启用。
启动超时首次 npx/uvx 下载包较慢（国内网络尤其明显）。用 MCP_TIMEOUT=10000 claude 调大启动超时（单位毫秒），或先手动运行一次把包缓存下来。
工具输出过长被截断输出超过 10,000 token 会警告，默认上限 25,000 token，可用 MAX_MCP_OUTPUT_TOKENS=50000 调整。
警告 “Leading or trailing whitespace”粘贴 token 时带了换行或空格，Claude Code 不会自动去掉，需要手动改配置。
同名服务器冲突警告同一个名字在多个作用域定义了不同端点，用 claude mcp remove 名称 --scope 作用域 删掉多余的。
提示缺少环境变量.mcp.json 里引用的 ${VAR} 没设置，设置它或写成 ${VAR:-默认值}。

5. 国内使用提示

很多 MCP 服务器依赖海外 API（搜索、SaaS 服务），需要能访问对应服务才能用；本地 stdio 服务器的安装依赖 npm/PyPI，可以配置国内镜像加速。本站暂未逐一实测各服务器在国内的可用性。

浏览全部 MCP 服务器 →

参考来源