mcp-config

用途

mcp-config 是一个用于在 Claude Code 中正确配置 MCP（Model Context Protocol）服务器的技能。它的核心目标是确保 MCP 服务器被配置在正确的位置和范围内，以免在所有会话中加载不必要的 MCP，造成上下文空间浪费。

主要能力

该技能覆盖以下工作内容：

新增 MCP 服务器到项目。
移除或禁用 MCP 服务器。
排查 MCP 在不该加载时被加载的问题。
清理 MCP 配置。
理解某个 MCP 为什么加载或不加载。

使用方式

技能给出了可直接照做的触发示例，例如：

添加 pencil MCP 到当前项目
从所有项目中移除 shadcn-studio-mcp
检查当前的 MCP 配置
清理全局 MCP 配置

配置流程包括四个步骤：检查当前 MCP 状态、将 MCP 添加到当前项目、移除 MCP 配置、清理 settings.json。技能提供了对应的检查与清理命令，例如查看用户级与项目级配置：

# Check user-level configuration
cat ~/.claude.json | grep -A 20 '"mcpServers"' | head -25

# Check project-level configuration
cat .mcp.json 2>/dev/null || echo "No project .mcp.json found"

# Check settings.json (should NOT have MCP config)
cat ~/.claude/settings.json | grep -A 5 '"permissions"'

项目级 .mcp.json 的推荐结构示例：

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

技能还给出了使用 Python 脚本移除全局配置和项目配置中 MCP 的示例代码，以及清理 settings.json 中 MCP 相关 permissions 的代码。

清理全局与 settings.json、并创建项目级配置的完整示例命令：

# 1. Clean up global config
python3 << 'EOF'
import json
with open('/Users/likai/.claude.json', 'r') as f:
    data = json.load(f)
data['mcpServers'] = {}
with open('/Users/likai/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)
print("✓ Cleaned global mcpServers")
EOF

# 2. Clean up settings.json
python3 << 'EOF'
import json
with open('/Users/likai/.claude/settings.json', 'r') as f:
    data = json.load(f)
if 'permissions' in data:
    del data['permissions']
with open('/Users/likai/.claude/settings.json', 'w') as f:
    json.dump(data, f, indent=2)
print("✓ Cleaned settings.json permissions")
EOF

# 3. Create project-level config
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "your-mcp-name": {
      "type": "stdio",
      "command": "your-command",
      "args": [],
      "env": {}
    }
  }
}
EOF
echo "✓ Created project .mcp.json"

# 4. Restart Claude Code
echo "⚠️  Please restart Claude Code for changes to take effect"

技能文档中还列出了常见 MCP 服务器的配置示例，包括 Pencil（设计工具）、Shadcn Studio 与 Unsplash：

{
  "mcpServers": {
    "pencil": {
      "command": "/Users/likai/.vscode/extensions/highagency.pencildev-0.6.29/out/mcp-server-darwin-arm64",
      "args": ["--app", "visual_studio_code"],
      "env": {},
      "type": "stdio"
    }
  }
}

{
  "mcpServers": {
    "shadcn-studio-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "shadcn-studio-mcp",
        "API_KEY=your-api-key",
        "EMAIL=your-email"
      ],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "unsplash": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microlee666/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

关键概念

文档强调只有两个位置是有效的 MCP 配置位置：

用户/本地范围：~/.claude.json，位于 mcpServers 字段（对所有项目全局生效），或位于特定项目路径下（用户配置中的项目专属配置）。
项目范围：项目根目录的 .mcp.json，可纳入源码控制，只影响当前项目。

重要规则：不要在 ~/.claude.json 的全局 mcpServers 中配置 MCP，因为这会在所有会话中加载并浪费上下文空间；应在项目级 .mcp.json 中配置；避免用 settings.json 控制 MCP，因为 permissions.allow 字段可能覆盖 disabled 设置并造成混乱。

配置优先级

Claude Code 加载 MCP 时遵循以下优先级：

项目级 .mcp.json（最高优先级）
用户级 ~/.claude.json 项目专属配置
用户级 ~/.claude.json 全局 mcpServers

settings.json 的 permissions 可以覆盖以上所有配置。建议只使用项目级 .mcp.json，以避免混乱。

排查常见问题

MCP 在所有会话中加载：原因是配置在 ~/.claude.json 全局 mcpServers；解决办法是从全局配置移除、改为添加到项目级 .mcp.json、重启 Claude Code 会话。
MCP 设置了 "disabled": true 仍无法禁用：原因是 settings.json 中的 permissions.allow 覆盖了 disabled 设置；解决办法是移除 settings.json permissions 中的 MCP 项，若为空则删除整个 permissions 块，重启会话。
MCP 配置冲突：原因是多个位置配置了不同设置；解决办法是检查 ~/.claude.json、.mcp.json、settings.json 三个位置，只保留一处（优先 .mcp.json），移除其他位置。
找不到 MCP 配置在哪里：文档提供了诊断命令，分别检查全局配置、项目配置、用户 settings、项目 settings。

最佳实践

始终使用项目级 .mcp.json 配置项目专属 MCP。
保持 ~/.claude.json 全局 mcpServers 为空，避免上下文污染。
避免在 settings.json 中配置 MCP，必要时只用于 permissions。
配置变更后重启 Claude Code 以确保生效。
将 .mcp.json 纳入源码控制，让团队成员获得相同 MCP。
不要使用 disabled: true，直接彻底移除 MCP 配置。
不要混用多个配置位置，选定一处并保持一致。

适用场景与限制

适用于管理 Claude Code 中 MCP 服务器的配置、清理与排查。文档范围集中在 Claude Code 的配置文件位置、优先级与排查方法；对于其他客户端或平台的 MCP 配置方式，资料未提供。