Claude Desktop MCP設定ガイド — claude_desktop_config.jsonの場所と書き方

claude_desktop_config.json は、Claude DesktopにローカルのMCPサーバーを登録するための設定ファイルです。MCP(Model Context Protocol)は、AIと外部ツールをつなぐ標準プロトコルを指します。ファイルシステム、データベース、TerraformやPulumiのIaCツール、社内ツールなど、公開ディレクトリに並んでいないサーバーを自分で接続したいときはこのファイルを直接編集します。

置き場所は、macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json です。Windowsでは %APPDATA%\Claude\claude_desktop_config.json にあります。書き方は、mcpServers キーの下にサーバー名ごとの command と args を並べるだけです。ログは %APPDATA%\Claude\logs(Windows)か ~/Library/Logs/Claude(macOS)に出ます。

本稿は、ファイルの置き場所、mcpServers の構文、保存後の反映手順、動かないときの切り分けを扱います。あわせてClaude Code v2.1.285で、claude mcp add-json を使いサーバー名の規則を試した結果も載せます。Desktopの設定を取り込む claude mcp add-from-claude-desktop 自体は実行していません。Claude Code側の設定はClaude Code MCP設定ガイドが対応します。

claude_desktop_config.jsonとは何か

claude_desktop_config.json とは、Claude Desktopの起動時に自動で立ち上げるローカルMCPサーバーの一覧を書くJSON形式の設定ファイルです。サーバーごとに起動コマンド・引数・環境変数を指定でき、保存してアプリを再起動するとその通りにプロセスが立ち上がります。

Claude DesktopでMCPサーバーを使う方法はこれだけではありません。用途によって選ぶ経路が変わります。

ディレクトリに並んでいる有名なサーバーを使うだけなら、.mcpb 形式のDesktop Extensionsのほうが依存関係の解決やアップデートを肩代わりしてくれるぶん手間が少なくなります。この仕組みはDesktop Extensions(.mcpb)解説で扱っています。環境変数や起動引数を細かく制御したいときも、.mcpb ではなくこのファイルを使います。

設定ファイルの場所

ファイルはOSごとに決まった場所にあります。

パスを手打ちで探す必要はありません。Claude Desktopのメニューバーから「Settings」を開き、左サイドバーの「Developer」タブに入ります。「Edit Config」を押すと、ファイルが無ければ新規作成され、既存ならそのまま開きます。

mcpServersの書き方

設定ファイルの中身は mcpServers キー1つの直下に、サーバー名をキーにしたオブジェクトを並べる形です。ファイルシステムへのアクセスを許可する例を見てみます。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

各キーの役割は次の通りです。

環境変数を追加したいサーバーでは env を足します。

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key-here"
      }
    }
  }
}

stdio(標準入出力)経由で起動するMCPサーバーは、OSが自動で渡す環境変数の一部しか継承しません。サーバーの実行に特定の環境変数が要るなら、OSに設定済みであっても env に明示する必要があります。

パスは絶対パスで書きます。公式のトラブルシューティングも、設定内のパスは相対パスでなく絶対パスにするよう求めています。クライアントの設定から起動したサーバーの作業ディレクトリは未定義になりえ、macOSでは / になる場合があるためです。./data のような相対パスは、意図した場所を指さないことがあります。

リモートサーバーはこのファイルでは設定できない

claude_desktop_config.json は、ローカルで起動するサーバーを登録するためのファイルです。インターネット上でホストされたリモートMCPサーバーに接続したい場合は、このファイルではなく設定画面の「Connectors」から「カスタムコネクターを追加」を使います。公式もこの2つを別の仕組みとして扱っています。

両者は接続経路そのものが違います。カスタムコネクター経由の通信はAnthropicのクラウドインフラを経由し、ローカルのネットワークインターフェースを使いません。そのため社内ネットワークやVPNの奥にあるリモートサーバーは、Anthropic側のIPレンジからの着信を許可していないと接続できません。claude_desktop_config.json に書いたローカルサーバーは、これとは逆に手元のマシン上でプロセスとして直接動きます。ローカルサーバーは手元のマシンで起動するので、ファイルを編集した端末のClaude Desktopでしか動きません。カスタムコネクターはClaude・Cowork・Claude Desktopで使えますが、claude_desktop_config.json で設定したローカルサーバーはCoworkやclaude.aiでは使えません。

なお、Desktopアプリの中のCodeタブ(ローカルセッション)は、この claude_desktop_config.json を読み込みます。ここに書いたサーバーはチャットでもCodeタブでも使えます。同じ名前のサーバーを ~/.claude.json や .mcp.json にも書いた場合、Codeタブが使うのは claude_desktop_config.json 側の定義です。

「リモートのMCPサーバーに繋がらない」と感じたら、まず設定ファイルではなく「Connectors」画面から追加できているかを確認します。

設定を反映させる手順

サーバー定義を消して保存し、再起動すれば、そのサーバーは立ち上がらなくなります。

よくあるつまずき

JSON構文エラー。カンマの付け忘れや付け過ぎがあると読み込めません。エディタのJSON構文チェックを通してから保存します。

相対パスを書いてしまう。args に渡すパスは絶対パスで統一します。~ は使わず、/Users/username/... のようにフルパスで書きます。

npxがグローバルに入っていない。npx によるサーバー起動が失敗し続ける場合、npmがグローバルにインストールされているか確認します。%APPDATA%\npm (Windows)が存在しなければ npm install -g npm を実行します。

Windowsで %APPDATA% が展開されない。ログに ${APPDATA} を含むパスのエラーが出た場合、展開済みの値を env キーへ明示的に渡すと解決します。

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
        "BRAVE_API_KEY": "..."
      }
    }
  }
}

ツールが出ないのではなく、接続エラーのトーストが出る場合は、設定ではなくアプリ側の不具合の可能性があります。起動時のエラーはProtocol instance reuseエラーで扱っています。

ここまでで解決しない場合、command と args の値をそのままターミナルに貼って単体実行すると、Claude Desktop越しでは見えないエラーがその場で出ます。それでも分からなければログを確認します。

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Windowsでは %APPDATA%\Claude\logs にログファイルが並びます。mcp.log にMCP接続全体のログが、mcp-server-{サーバー名}.log にサーバーごとの標準エラー出力が記録されます。コマンドプロンプトなら次のように表示できます。

type "%APPDATA%\Claude\logs\mcp*.log"

ログでも原因が分からない場合は、DevToolsを開きます。Claude Desktop本体にChromeのDevToolsを組み込む機能があり、クライアント側のエラーをコンソールで直接確認できます。設定フォルダ(macOSは ~/Library/Application Support/Claude/、Windowsは %APPDATA%\Claude\)に次の内容で developer_settings.json を作成し、アプリを再起動します。

{
  "allowDevTools": true
}

再起動後、macOSは Command+Option+I、Windowsは Ctrl+Alt+I でDevToolsが開きます。本体用とタイトルバー用の2つのウィンドウが表示されるので、本体側のConsoleパネルでエラーを確認します。

Claude Codeへ持っていくときサーバー名で弾かれる

同じ「MCPをClaudeに繋ぐ」作業でも、Claude DesktopとClaude Codeでは設定ファイルもコマンドも別物です。

Desktopで設定済みのサーバーは、claude mcp add-from-claude-desktop で対話的に選んで取り込めます。macOSとWSL(Windows Subsystem for Linux)専用で、ネイティブのWindowsでは使えません。スコープの使い分けはClaude Code MCP設定ガイドが対応します。

落とし穴は名前の文字種です。Claude Desktopはサーバー名に制限を設けませんが、Claude Codeは英数字・ハイフン・アンダースコアしか受け付けません。Claude Code v2.1.285で、ホームを作業用ディレクトリに差し替えた環境から claude mcp add-json で名前の検査だけを試しました。

claude mcp add-json "my server" '{"command":"npx","args":["-y","x"]}'
claude mcp add-json "my.server" '{"command":"npx","args":["-y","x"]}'
claude mcp add-json "my-server_1" '{"command":"/opt/x/server","args":["--flag"]}'

出力は次の通りでした。

Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
Invalid name my.server. Names can only contain letters, numbers, hyphens, and underscores.
Added stdio MCP server my-server_1 to local config

スペースもピリオドも同じ文言で弾かれ、ハイフンとアンダースコアだけの名前は通りました。取り込みの公式説明では、弾いた名前を個別に報告しつつ、ほかのサーバーは取り込まれます。v2.1.205より前は、最初に無効な名前が出た時点で取り込み全体が止まっていました。Claude Codeでも使う予定があるサーバーは、Desktop側で最初から brave-search のように名付けておくと手戻りがありません。

取り込み後の設定は、既定のスコープ(local)ではそのプロジェクトの下に入ります。上の実験で書き込まれた ~/.claude.json では、projects 以下のプロジェクトパスの mcpServers に、command と args だけが保存されていました。上のコマンドには env を渡していないため、env のキーはありません。

MCPの仕組み自体から知りたい場合はMCPとは — AIと外部ツールをつなぐ標準プロトコル、Claude Code全体の使い方は完全ガイドが入口です。サーバーに繋がらない症状の切り分けは、Claude Code向けですが考え方は共通するMCPサーバーに接続できないときの切り分け手順にあります。

まとめ

DesktopとClaude Codeの両方で同じサーバーを使うなら、claude_desktop_config.json を定義の元にする構成が成り立ちます。Codeタブはこのファイルの定義を優先し、claude mcp add-from-claude-desktop での取り込みも同じ定義を読むためです。その場合はサーバー名を最初から英数字・ハイフン・アンダースコアだけで付けておきます。