mcp-config

MCP 配置管理

概述

此技能可帮助你在 Claude Code 中正确配置 MCP 服务，确保 MCP 服务配置在正确的位置和作用域，避免在所有会话中造成不必要的上下文污染。

核心概念

两个有效的配置位置

只有以下两个位置可用于 MCP 配置：

1. 用户／本地作用域：~/.claude.json

   • 位于 mcpServers 字段中（适用于所有项目）
   • 或位于特定项目路径下（用户配置中的项目专属配置）

2. 项目作用域：项目根目录中的 .mcp.json

   • 纳入源代码管理
   • 仅影响当前项目

⚠️ 重要规则

• 不要在 ~/.claude.json 的全局 mcpServers 中配置 MCP——这会在所有会话中加载 MCP，浪费上下文空间
• 请在项目级 .mcp.json 中配置 MCP——这只会在处理相应项目时加载 MCP
• 避免使用 settings.json 控制 MCP——permissions.allow 字段可能覆盖禁用设置，造成混淆

何时使用此技能

在以下情况下调用此技能：

• 向项目添加新的 MCP 服务
• 移除／禁用 MCP 服务
• MCP 服务在不该加载时被加载
• 需要清理 MCP 配置
• 想了解 MCP 为何加载或未加载

快速入门

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

---

配置工作流

1. 检查当前 MCP 状态

首先，了解当前加载了哪些 MCP：

# 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"'

2. 将 MCP 添加到当前项目

最佳实践：始终在项目级别添加 MCP

在项目根目录中创建或编辑 .mcp.json：

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

3. 移除 MCP 配置

从全局配置中移除（~/.claude.json）：

import json

with open('/Users/likai/.claude.json', 'r') as f:
    data = json.load(f)

# Remove from global mcpServers
if 'mcpServers' in data and 'server-name' in data['mcpServers']:
    del data['mcpServers']['server-name']
    print(f"Removed server-name from global config")

with open('/Users/likai/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)

从项目配置中移除（.mcp.json）：

import json

try:
    with open('.mcp.json', 'r') as f:
        data = json.load(f)

    if 'mcpServers' in data and 'server-name' in data['mcpServers']:
        del data['mcpServers']['server-name']

    with open('.mcp.json', 'w') as f:
        json.dump(data, f, indent=2)
    print("Removed server-name from project config")
except FileNotFoundError:
    print("No .mcp.json found in project")

4. 清理 settings.json

移除可能覆盖配置的所有 MCP 相关权限：

import json

with open('/Users/likai/.claude/settings.json', 'r') as f:
    data = json.load(f)

# Remove permissions block if it contains MCP references
if 'permissions' in data:
    if 'allow' in data['permissions']:
        data['permissions']['allow'] = [
            item for item in data['permissions']['allow']
            if not item.startswith('mcp__')
        ]
        if not data['permissions']['allow']:
            del data['permissions']

with open('/Users/likai/.claude/settings.json', 'w') as f:
    json.dump(data, f, indent=2)

---

常见 MCP 服务

Pencil（设计工具）

{
  "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"
    }
  }
}

Shadcn Studio

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

Unsplash

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

---

故障排除

问题：MCP 在所有会话中加载

原因：MCP 配置在 ~/.claude.json 的全局 mcpServers 中

解决方案：

1. 从 ~/.claude.json 全局配置中移除
2. 改为添加到项目级 .mcp.json
3. 重启 Claude Code 会话

问题：即使设置了 "disabled": true，MCP 仍无法禁用

原因：settings.json 中的 permissions.allow 覆盖了禁用设置

解决方案：

1. 从 settings.json 的权限中移除 MCP
2. 如果 permissions 块为空，则移除整个块
3. 重启 Claude Code 会话

问题：MCP 配置冲突

原因：MCP 在多个位置配置了不同的设置

解决方案：

1. 检查所有三个位置：~/.claude.json、.mcp.json、settings.json
2. 仅在一个位置保留配置（优先使用 .mcp.json）
3. 从其他位置移除

问题：找不到 MCP 的配置位置

诊断命令：

# Search all possible locations
echo "=== Global Config ==="
grep -A 10 '"mcpServers"' ~/.claude.json | head -15

echo "=== Project Config ==="
cat .mcp.json 2>/dev/null || echo "No .mcp.json"

echo "=== Settings ==="
grep -A 5 '"permissions"' ~/.claude/settings.json 2>/dev/null || echo "No permissions"

echo "=== Project Settings ==="
grep -A 5 '"permissions"' .claude/settings.json 2>/dev/null || echo "No project settings"

---

最佳实践

1. ✅ 始终使用项目级 .mcp.json 配置项目专属的 MCP
2. ✅ 保持 ~/.claude.json 的全局 mcpServers 为空，避免上下文污染
3. ✅ 避免在 settings.json 中配置 MCP——仅在需要时将其用于权限设置
4. ✅ 配置更改后重启 Claude Code，确保更改生效
5. ✅ 纳入源代码管理——提交 .mcp.json，让团队成员使用相同的 MCP
6. ❌ 不要使用 disabled: true——直接移除整个 MCP 配置
7. ❌ 不要混用配置位置——选择一个位置并始终使用它

---

配置优先级

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

1. 项目级 .mcp.json（最高优先级）
2. 用户级 ~/.claude.json 中针对项目的配置
3. 用户级 ~/.claude.json 中的全局 mcpServers
4. settings.json 权限可以覆盖以上所有配置

建议：仅使用项目级 .mcp.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"

---

总结

• 两个有效位置：~/.claude.json 和 .mcp.json
• 最佳实践：仅使用项目级 .mcp.json
• 避免：在 ~/.claude.json 中配置全局 mcpServers（会浪费上下文）
• 避免：在 settings.json 中配置 MCP（会导致冲突）
• 配置更改后务必重启 Claude Code