Soup's Blog

Back

MCP 管理

Claude Code MCP 服务器配置与管理教程
}

MCP 管理教程#

MCP (Model Context Protocol) 是一种开放协议，使 AI 助手能够与系统工具和数据源进行安全、标准化的连接。

添加 MCP 服务器#

选项 1：添加远程 HTTP 服务器#

HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式。

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

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

# 带有 Bearer 令牌的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
bash

选项 2：添加本地 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
bash

重要：选项顺序#

所有选项（--transport、--env、--scope、--header）必须在服务器名称之前。然后 --（双破折号）将服务器名称与传递给 MCP 服务器的命令和参数分开。

例如：

  • claude mcp add --transport stdio myserver -- npx server → 运行 npx server
  • claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 运行 python server.py --port 8080，环境中有 KEY=value

这可以防止 Claude 的标志与服务器标志之间的冲突。

注意事项#

Claude Code 当前不支持添加远程 SSE 服务器

高级配置#

动态工具更新#

Claude Code 支持 list_changed 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。

当 MCP 服务器发送 list_changed 通知时，Claude Code 会自动刷新来自该服务器的可用功能。

配置选项#

使用 —scope 标志#

指定配置的存储位置：

  • local（默认）：仅在当前项目中对您可用（在较旧版本中称为 project）
  • project：通过 .mcp.json 文件与项目中的每个人共享
  • user：在所有项目中对您可用（在较旧版本中称为 global）
claude mcp add --scope project my-server -- npx my-mcp-server
bash

使用 —env 标志#

设置环境变量：

claude mcp add --transport stdio --env API_KEY=your-key my-api -- npx my-server
bash

配置超时#

使用 MCP_TIMEOUT 环境变量配置 MCP 服务器启动超时：

MCP_TIMEOUT=10000 claude mcp add my-server -- npx my-server
bash

设置 10 秒超时。

配置输出令牌限制#

当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制：

MAX_MCP_OUTPUT_TOKENS=50000 claude mcp add my-server -- npx my-server
bash

OAuth 2.0 身份验证#

对于需要 OAuth 2.0 身份验证的远程服务器，使用 /mcp 命令：

/mcp
bash

Windows 用户特殊处理#

在 Windows（不是 WSL）上，使用 npx 的本地 MCP 服务器需要 cmd /c 包装器以确保正确执行。

# 这创建了 Windows 可以执行的 command="cmd"
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
bash

没有 cmd /c 包装器，您会遇到”连接已关闭”错误，因为 Windows 无法直接执行 npx。

管理 MCP 服务器#

查看已添加的服务器#

claude mcp list
bash

删除 MCP 服务器#

claude mcp remove <name>
bash

测试 MCP 服务器#

claude mcp test <name>
bash

常见问题#

连接失败#

  • 检查服务器名称是否正确
  • 验证命令或 URL 是否有效
  • 确保 --transport 参数正确指定
  • Windows 用户检查是否使用了 cmd /c 包装器

工具未显示#

  • 确保 MCP 服务器已正确启动
  • 检查是否有权限问题
  • 查看服务器日志输出