mcp-server-manager

MCP 服务管理器

概述

MCP（模型上下文协议）服务将 Claude Code 连接到外部工具、数据库和 API。本技能介绍如何使用 claude mcp 命令行界面安装、配置和管理 MCP 服务。

快速参考

基本命令

列出所有已配置的 MCP 服务：

claude mcp list

获取特定服务的详细信息：

claude mcp get <server-name>

移除服务：

claude mcp remove <server-name>

检查服务状态（在 Claude Code 中）：

/mcp

添加 MCP 服务

传输类型

MCP 服务使用三种传输协议之一。根据服务类型选择合适的传输方式：

HTTP 传输（远程服务）

适用于提供 HTTP 端点的云服务：

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: Add Notion server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

SSE 传输（服务器发送事件）

适用于使用 SSE 协议的远程服务：

# Basic syntax
claude mcp add --transport sse <name> <url>

# Example: Add Webflow server
claude mcp add --transport sse webflow https://mcp.webflow.com/sse

# With API key header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: YOUR_KEY"

Stdio 传输（本地进程）

适用于通过 stdio 通信运行的本地进程服务：

# Basic syntax
claude mcp add --transport stdio <name> [--env KEY=VALUE ...] -- <command> [args...]

# Example: Add Airtable server
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

# Example: Add local Python server
claude mcp add --transport stdio custom-db \
  --env DB_URL=postgresql://localhost/mydb \
  -- python3 /path/to/server.py

重要：在命令前使用 -- 分隔符，标明环境变量的结束位置和命令的起始位置。

配置范围

MCP 服务可以配置在三个不同的范围：

本地范围（默认）

仅对当前项目目录可见。适用于：

• 个人开发服务
• 实验性配置
• 包含敏感凭据的服务

# Local scope (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

项目范围

通过项目根目录中的 .mcp.json 与团队成员共享。适用于：

• 团队共享的服务
• 项目专用工具
• 受版本控制的配置

# Add project-scoped server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

创建或更新 .mcp.json：

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

安全提示：Claude Code 在使用项目范围的服务之前会提示请求批准。使用以下命令重置批准设置：

claude mcp reset-project-choices

用户范围

可用于此计算机上的所有项目。适用于：

• 个人实用服务
• 跨项目使用的开发工具
• 常用服务

# Add user-scoped server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

范围优先级

当多个范围中存在同名服务时： 本地 > 项目 > 用户

身份验证

OAuth 2.0（远程服务）

许多远程 MCP 服务使用 OAuth。身份验证流程：

1. 使用 claude mcp add 添加服务
2. 首次使用时会触发 OAuth 浏览器流程
3. 在浏览器中授权
4. 凭据存储在 ~/.mcp-auth/

以 Webflow 为例：

# Add server
claude mcp add --transport sse webflow https://mcp.webflow.com/sse

# Check status - shows "⚠ Needs authentication"
claude mcp list

# Within Claude Code, trigger OAuth
# Ask: "List my Webflow sites"
# Browser opens for authorization

重置 OAuth 凭据：

rm -rf ~/.mcp-auth

API 密钥和标头

对于需要 API 密钥或自定义标头的服务：

# Bearer token
claude mcp add --transport http api-server https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# API key header
claude mcp add --transport sse service https://service.com/sse \
  --header "X-API-Key: YOUR_KEY"

# Multiple headers
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer TOKEN" \
  --header "X-Custom-Header: VALUE"

环境变量（Stdio 服务）

通过环境变量传递敏感凭据：

claude mcp add --transport stdio database \
  --env DB_PASSWORD=secret123 \
  --env API_KEY=key456 \
  -- python3 /path/to/db-server.py

故障排除

常见问题

服务显示“⚠ Needs authentication”

• 远程服务需要 OAuth
• 使用该服务的工具以触发身份验证
• 使用 claude mcp get <name> 检查身份验证状态

服务显示“✗ Connection failed”

• 确认 URL 正确
• 检查网络连接
• 确保身份验证凭据有效
• 对于 stdio 服务，检查命令路径和权限

服务未显示在列表中

• 如果刚添加服务，请重启 Claude Code CLI
• 检查范围——服务可能位于其他范围
• 确认配置文件语法正确

项目范围的服务需要重复批准

• Claude Code 会在首次使用时请求批准，以此作为安全措施
• 出现提示时，选择“Approve once”或“Always approve”
• 使用 claude mcp reset-project-choices 重置选择

配置文件位置

本地范围：项目专用设置，位于 .claude/settings.local.json 项目范围：项目根目录中的 .mcp.json 用户范围：~/.claude/settings.json

调试

启用 MCP 调试模式：

claude --mcp-debug

或使用较新的调试标志：

claude --debug

检查服务详情：

# Get server configuration
claude mcp get <server-name>

# List all servers with status
claude mcp list

高级用法

在 .mcp.json 中展开环境变量

项目范围的配置支持环境变量展开：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

语法：

• ${VAR} - 展开环境变量
• ${VAR:-default} - 如果未设置，则使用默认值

从 Claude Desktop 导入

如果已在 Claude Desktop 中配置了 MCP 服务：

claude mcp add-from-claude-desktop

从 Claude Desktop 配置中导入服务（仅限 macOS 和 WSL）。

从 JSON 配置导入

直接导入 JSON 配置：

claude mcp add-json <name> '<json-config>'

示例：

claude mcp add-json my-server '{
  "command": "npx",
  "args": ["-y", "server-package"],
  "env": {"API_KEY": "value"}
}'

MCP 输出限制

控制 MCP 工具的最大输出令牌数：

# Set custom limit (default: 25,000 tokens)
export MAX_MCP_OUTPUT_TOKENS=50000
claude

适用于以下类型的服务：

• 查询大型数据集
• 生成详细报告
• 处理大量日志

常见 MCP 服务

请参阅完整的 MCP 文档，了解各类别中大量热门 MCP 服务：

• 开发与测试：Sentry、Socket、Hugging Face、Jam
• 项目管理：Asana、Atlassian、Linear、Notion、Monday
• 数据库：Airtable、HubSpot、PostgreSQL
• 支付：PayPal、Plaid、Square、Stripe
• 设计：Figma、Canva、InVideo
• 基础设施：Cloudflare、Netlify、Vercel
• 自动化：Workato、Zapier

资源

references/mcp_documentation.md

完整的 MCP 文档，包括：

• 包含安装命令的全面服务目录
• 详细的传输协议规范
• 身份验证方法和 OAuth 流程
• 基于插件的 MCP 服务
• 企业级 MCP 配置
• 环境变量展开语法
• 实用示例和用例

适用于以下情况：

• 需要特定 MCP 服务的安装命令
• 排查复杂的配置问题
• 设置企业级 MCP 部署
• 了解传输协议详情