12.1 添加 MCP 服务器

学习如何添加不同类型的 MCP 服务器到 Claude Code。

添加远程 HTTP 服务器#

HTTP 服务器是连接到远程 MCP 服务器的推荐选项。

基本语法#

bash
复制
claude mcp add --transport http name>url>

示例：连接到 Notion#

bash
复制
claude mcp add --transport http notion https://mcp.notion.com/mcp

带身份验证的示例#

bash
复制
# Bearer 令牌claude mcp add --transport http secure-api https://api.example.com/mcp \--header "Authorization: Bearer your-token"
# API 密钥claude mcp add --transport http api https://api.example.com/mcp \--header "X-API-Key: your-api-key"

带多个标头的示例#

bash
复制
claude mcp add --transport http custom-api https://api.example.com/mcp \  --header "Authorization: Bearer your-token"\  --header "X-Custom-Header: custom-value"

添加远程 SSE 服务器#

SSE（Server-Sent Events）传输已弃用，请在可用的地方使用 HTTP 服务器。

基本语法#

bash
复制
claude mcp add --transport sse name>url>

示例：连接到 Asana#

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

带身份验证的示例#

bash
复制
claude mcp add --transport sse private-api https://api.company.com/sse \--header "X-API-Key: your-key-here"

添加本地 stdio 服务器#

Stdio 服务器作为本地进程在您的计算机上运行。

基本语法#

bash
复制
claude mcp add --transport stdio name>command>[args...]

示例：添加 Airtable 服务器#

bash
复制
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \-- npx -y airtable-mcp-server

示例：添加数据库服务器#

bash
复制
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

示例：添加 Python 服务器#

bash
复制
claude mcp add --transport stdio python-server -- python server.py

使用 -- 参数#

--（双破折号）将 Claude 自己的 CLI 标志与传递给 MCP 服务器的命令和参数分开。

bash
复制
# 运行 npx serverclaude mcp add --transport stdio myserver -- npx server

# 运行 python server.py --port 8080claude mcp add --transport stdio myserver --env KEY=value -- python server.py --port 8080

Windows 用户注意事项#

在本机 Windows（不是 WSL）上，使用 npx 的本地 MCP 服务器需要 cmd /c 包装器：

bash
复制
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

配置选项#

环境变量#

使用 --env 标志设置环境变量：

bash
复制
claude mcp add --transport stdio db \  --env DB_URL=postgresql://user:pass@localhost/db \  --env DB_TIMEOUT=30\  -- npx -y db-server

作用域#

使用 --scope 标志指定配置的存储位置：

bash
复制
# 本地范围（默认）claude mcp add --transport http github https://api.github.com/mcp/

# 项目范围claude mcp add --transport http github --scope project https://api.github.com/mcp/

# 用户范围claude mcp add --transport http github --scope user https://api.github.com/mcp/

超时设置#

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

bash
复制
# 设置 10 秒超时MCP_TIMEOUT=10000 claude

输出限制#

使用 MAX_MCP_OUTPUT_TOKENS 环境变量增加输出限制：

bash
复制
# 设置 50,000 令牌限制MAX_MCP_OUTPUT_TOKENS=50000 claude

身份验证#

OAuth 2.0#

许多基于云的 MCP 服务器需要 OAuth 2.0 身份验证：

bash
复制
# 1. 添加服务器claude mcp add --transport http github https://api.github.com/mcp/

# 2. 在 Claude Code 中进行身份验证/mcp

# 3. 选择需要身份验证的服务器# 4. 按照 OAuth 流程完成身份验证

API 密钥#

使用 API 密钥进行身份验证：

bash
复制
claude mcp add --transport http api https://api.example.com/mcp \--header "Authorization: Bearer your-api-key"

环境变量#

使用环境变量传递凭证：

bash
复制
claude mcp add --transport stdio db \  --env API_KEY=your-key \  -- npx -y db-server

验证安装#

检查服务器状态#

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

# 获取特定服务器的详细信息claude mcp get github

# 在 Claude Code 中检查服务器状态/mcp

测试服务器连接#

bash
复制
# 测试服务器连接测试 MCP 服务器连接

# 使用服务器工具使用 GitHub 工具查看 PR

常见问题#

连接失败#

解决方案: