🗂

Claude Code MCP サーバー設定とスコープ管理方法まとめ

2025/08/16に公開

Model Context Protocol

Claude Code

MCP サーバー

tech

概要

Claude Code（CLI）では、みなさんご存知 MCP（Model Context Protocol）サーバーを登録して使うことができます。その際に重要になるのが スコープ です。MCP のスコープの違いと、実際にユーザースコープに MCP サーバーを追加する方法、私が困った部分について解説します。

MCP サーバーのスコープとは

Claude Code では MCP サーバーを登録する際に、どの範囲で有効にするかを スコープ として指定できます。主なスコープは以下の 3 つです。

1. プロジェクトスコープ（project）

設定ファイル: プロジェクト直下の .mcp.json
用途: チーム開発やリポジトリで共有したい MCP 設定

// プロジェクトルートに置く .mcp.json
{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-search"]
    }
  }
}

2. ローカルスコープ（local）

設定ファイル: ~/.claude.json の projects セクション
用途: 自分の PC 上で、特定のプロジェクトにだけ適用する設定

// ~/.claude.json
{
  "projects": {
    "/Users/you/dev/my-app": {
      "mcpServers": {
        "filesystem": {
          "command": "node",
          "args": ["/path/to/mcp-server-fs"]
        }
      }
    }
  }
}

3. ユーザースコープ（user / global）

設定ファイル: ~/.claude.json の mcpServers 直下
用途: すべてのプロジェクトで共通して使いたい MCP 設定

// ~/.claude.json
{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "mcp-server-shell"]
    }
  }
}

コマンドで user スコープに追加する方法

ユーザースコープへの追加は以下のコマンドで行います。

claude mcp add -s user <name> -- <command> [args...]

例: Upstash の Context7 サーバーを追加する場合

claude mcp add -s user context7 -- npx --yes @upstash/context7-mcp

これを実行すると、~/.claude.json に次のような設定が追記されます。

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["--yes", "@upstash/context7-mcp"]
    }
  }
}

うまくいかないケースと正しい書き方

実際に以下のように書いた場合は失敗します。

claude mcp add context7 -- npx --yes @upstash/context7-mcp --scope user

出力されたエラー

MCP server context7 already exists in local config

原因

--scope user を -- の後ろに置いてしまうと、--scope user が外部コマンド (npx) の引数として解釈される
その結果、Claude CLI にはスコープ指定が渡らず、デフォルトの local スコープ に登録されてしまう
すでに local に同じ名前の MCP サーバーがあると「既存エラー」が出る

正しい書き方

claude mcp add -s user context7 -- npx --yes @upstash/context7-mcp

ここで -s user をサーバー名の直後に指定することで、正しく user スコープに追加されます。

まとめ

Claude Code の MCP 設定は project / local / user の 3 つのスコープに分かれる
user スコープに追加するには claude mcp add -s user を使う
-- 以降は外部コマンドの引数扱いになるため、--scope をそこに書くと無視される
スコープ指定は必ずサーバー名の直後に書くことが重要

この手順を理解すれば、任意の MCP サーバーをグローバルに登録して活用できる。

概要