12.3 MCP 服务器管理

第 12 章 · MCP 服务器配置与管理 · 第4部分：模型上下文协议 MCP

学习如何管理已配置的 MCP 服务器，包括列出、查看详情、删除和检查状态。

列出服务器#

列出所有服务器#

claude mcp list

输出示例:

bash
复制
已配置的 MCP 服务器：

本地范围：
- github: https://api.githubcopilot.com/mcp/
- sentry: https://mcp.sentry.dev/mcp

项目范围：
- database: stdio server
- api: http server

用户范围：
- formatter: stdio server

列出特定范围的服务器#

列出本地范围服务器

claude mcp list --scope local

列出项目范围服务器

claude mcp list --scope project

列出用户范围服务器

claude mcp list --scope user

bash
复制
## 获取服务器详情

### 基本用法

claude mcp get

示例：查看 GitHub 服务器详情#

bash
复制
claude mcp get github

输出示例:

bash
复制
服务器名称: github
传输方式: http
URL: https://api.githubcopilot.com/mcp/
范围: local
状态: 已连接
工具: 15
资源: 5

示例：查看数据库服务器详情#

bash
复制
claude mcp get database

输出示例:

bash
复制
服务器名称: database
传输方式: stdio
命令: npx -y @bytebase/dbhub
参数: --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
范围: project
状态: 已连接
工具: 8
资源: 3

删除服务器#

基本用法#

bash
复制
claude mcp remove server-name>

示例：删除 GitHub 服务器#

bash
复制
claude mcp remove github

输出:

bash
复制
确认删除服务器 github? (y/n): y
服务器 github 已成功删除

删除特定范围的服务器#

bash
复制
# 删除本地范围服务器claude mcp remove github --scope local
# 删除项目范围服务器claude mcp remove database --scope project

# 删除用户范围服务器claude mcp remove formatter --scope user

批量删除#

bash
复制
# 删除多个服务器claude mcp remove github sentry database

检查服务器状态#

在 Claude Code 中检查#

bash
复制
/mcp

输出示例:

bash
复制
MCP 服务器状态：
本地范围：
✅ github: 已连接 (15 工具, 5 资源)
✅ sentry: 已连接 (10 工具, 3 资源)
项目范围：
✅ database: 已连接 (8 工具, 3 资源)
❌ api: 连接错误
用户范围：
✅ formatter: 已连接 (5 工具, 0 资源)

检查特定服务器状态#

bash
复制
# 检查 GitHub 服务器状态claude mcp get github

输出示例:

bash
复制
GitHub 服务器状态：
- 状态: 已连接
- 响应时间: 100ms
- 最后检查: 2 分钟前
- 工具数量: 15
- 资源数量: 5

测试服务器连接#

测试所有服务器#

bash
复制
# 测试所有 MCP 服务器连接claude mcp list

输出示例:

bash
复制
测试 MCP 服务器连接：
✅ github: 连接成功 (50ms)
✅ sentry: 连接成功 (80ms)
✅ database: 连接成功 (30ms)
❌ api: 连接失败 - 超时

测试特定服务器#

bash
复制
# 测试 GitHub 服务器连接claude mcp get github

输出示例:

bash
复制
测试 GitHub 服务器连接：
✅ 连接成功
响应时间: 50ms
服务器版本: 1.2.3

更新服务器配置#

更新 HTTP 服务器#

bash
复制
# 删除旧配置claude mcp remove github

# 添加新配置claude mcp add --transport http github https://api.githubcopilot.com/mcp/v2

更新 stdio 服务器#

bash
复制
# 删除旧配置claude mcp remove database

# 添加新配置claude mcp add --transport stdio database \--env DB_URL=new-db-url \-- npx -y @bytebase/dbhub

更新环境变量#

bash
复制
# 对于项目范围服务器，编辑 .mcp.jsonvim .mcp.json

json
复制
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DB_URL": "${NEW_DB_URL:-postgresql://localhost/db}"
      }
    }
  }
}

重置配置#

重置项目选择#

bash
复制
claude mcp reset-project-choices

此命令将清除所有项目范围 MCP 服务器的批准选择。

重置所有配置#

bash
复制
# 删除所有本地范围服务器claude mcp list --scope local|awk'{print $1}'|xargs claude mcp remove

# 删除所有用户范围服务器claude mcp list --scope user |awk'{print $1}'|xargs claude mcp remove

监控服务器性能#

查看性能统计#

bash
复制
# 显示 MCP 服务器性能统计claude mcp list

输出示例:

bash
复制
MCP 服务器性能统计：

github:
- 平均响应时间: 100ms
- 总调用次数: 150
- 成功率: 99.3%
- 最后调用: 1 分钟前

sentry:
- 平均响应时间: 200ms
- 总调用次数: 50
- 成功率: 100%
- 最后调用: 5 分钟前

database:
- 平均响应时间: 50ms
- 总调用次数: 300
- 成功率: 98.7%
- 最后调用: 30 秒前

查看错误日志#

bash
复制
# 显示 MCP 服务器错误日志claude --verbose

输出示例:

bash
复制
MCP 服务器错误日志：

api:
- [2024-01-15 10:30:00] 连接超时
- [2024-01-15 10:35:00] API 限流

database:
- [2024-01-15 10:20:00] 查询超时
- [2024-01-15 10:25:00] 连接失败

故障排除#

服务器连接失败#

问题: 服务器无法连接

解决方案:

bash
复制
# 1. 检查服务器状态/mcp

# 2. 测试连接claude mcp list

# 3. 查看错误日志claude --verbose

# 4. 验证配置claude mcp get server-name

# 5. 重新配置服务器claude mcp remove server-name
claude mcp add --transport http server-name url>

服务器响应缓慢#

问题: 服务器响应时间过长

解决方案:

bash
复制
# 1. 查看性能统计claude mcp list

# 2. 检查网络连接ping api.example.com

# 3. 增加超时设置MCP_TIMEOUT=30000 claude

# 4. 优化服务器配置# 考虑使用更快的传输方式

工具调用失败#

问题: MCP 工具调用失败

解决方案:

bash
复制
# 1. 检查服务器状态/mcp

# 2. 验证工具参数# 检查工具参数
# 3. 查看错误日志claude --verbose

# 4. 重试工具调用# 重试工具调用

配置文件错误#

问题: .mcp.json 配置文件有错误

解决方案:

bash
复制
# 1. 验证 JSON 语法cat .mcp.json | jq .
# 2. 检查环境变量echo$API_KEY
# 3. 查看错误日志claude --verbose

# 4. 修复配置文件vim .mcp.json

最佳实践#

1. 定期检查服务器状态#

bash
复制
# 每天检查一次/mcp

2. 监控性能#

bash
复制
# 定期查看性能统计claude mcp list

# 识别慢速服务器# 优化配置或更换服务器

3. 及时删除不需要的服务器#

bash
复制
# 定期清理不使用的服务器claude mcp list
claude mcp remove unused-server

4. 备份配置#

bash
复制
# 备份 .mcp.jsoncp .mcp.json .mcp.json.backup

# 备份用户配置cp ~/.claude/mcp.json ~/.claude/mcp.json.backup

5. 文档化配置#

bash
复制
# 创建配置文档echo"MCP 服务器配置说明"> MCP_CONFIG.md
echo"- github: 用于代码审查">> MCP_CONFIG.md
echo"- database: 用于数据查询">> MCP_CONFIG.md

自动化管理#

使用脚本管理#

bash
复制
#!/bin/bash# mcp-manager.sh
# 列出服务器list_servers(){    claude mcp list
}
# 添加服务器add_server(){    claude mcp add"$@"}
# 删除服务器remove_server(){    claude mcp remove "$@"}
# 检查状态check_status(){echo"> /mcp"| claude
}
# 主函数case"$1"in    list) list_servers ;;add)shift; add_server "$@";;    remove)shift; remove_server "$@";;    status) check_status ;;    *)echo"用法: $0 {list|add|remove|status}";;esac

定期维护#

bash
复制
#!/bin/bash# mcp-maintenance.sh
# 检查所有服务器状态echo"检查 MCP 服务器状态..."claude mcp list

# 测试连接echo"测试服务器连接..."claude mcp list

# 查看性能统计echo"查看性能统计..."claude mcp list

# 备份配置echo"备份配置..."cp ~/.claude/mcp.json ~/.claude/mcp.json.backup.$(date +%Y%m%d)

设置定时任务#

bash
复制
# 添加到 crontabcrontab -e

# 每天凌晨 2 点运行维护脚本02 * * * /path/to/mcp-maintenance.sh