mcp-config

MCP 設定管理

概要

このスキルは、Claude Code で MCP サーバーを適切に設定するのに役立ちます。MCP サーバーを正しい場所とスコープに設定することで、すべてのセッションで不必要にコンテキストが消費されるのを防ぎます。

重要な概念

有効な設定場所は 2 つ

MCP の設定場所として有効なのは、次の 2 か所のみです。

1. ユーザー／ローカルスコープ：~/.claude.json

   • mcpServers フィールド内（すべてのプロジェクトに適用されるグローバル設定）
   • または、特定のプロジェクトパスの下（ユーザー設定内のプロジェクト固有の設定）

2. プロジェクトスコープ：プロジェクトルートの .mcp.json

   • ソース管理にチェックインします
   • 現在のプロジェクトのみに影響します

⚠️ 重要なルール

• ~/.claude.json のグローバルな mcpServers には MCP を設定しないでください — すべてのセッションで MCP が読み込まれ、コンテキスト領域が無駄になります
• プロジェクトレベルの .mcp.json に MCP を設定してください — そのプロジェクトで作業する場合にのみ MCP が読み込まれます
• MCP の制御に settings.json を使わないでください — 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. 3 つすべての場所を確認します：~/.claude.json、.mcp.json、settings.json
2. 設定は 1 か所だけに残します（.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 には、常にプロジェクトレベルの .mcp.json を使います
2. ✅ コンテキストの消費を避けるため、~/.claude.json のグローバルな mcpServers は空にしておきます
3. ✅ settings.json での MCP 設定は避け、必要な場合に限り権限の設定に使います
4. ✅ 設定変更を反映させるため、変更後は Claude Code を再起動します
5. ✅ ソース管理にチェックインします — .mcp.json をコミットして、チームメンバーも同じ MCP を使えるようにします
6. ❌ disabled: true は使わないでください — MCP 設定を完全に削除してください
7. ❌ 設定場所を混在させないでください — 1 か所を選び、そこに統一してください

---

設定の優先順位

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"

---

まとめ

• 有効な場所は2か所：~/.claude.json と .mcp.json
• ベストプラクティス：プロジェクトレベルの .mcp.json のみを使用する
• 避けること：~/.claude.json のグローバルな mcpServers（コンテキストを無駄に消費します）
• 避けること：settings.json の MCP 設定（競合の原因になります）
• 設定変更後は必ず Claude Code を再起動してください