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

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

本稿では、ファイルの置き場所、mcpServers の構文、保存後に反映させる手順、そしてつまずきやすい5つのポイントを順に確認します。Claude Codeでは同名のMCP接続でも仕様が異なります。設定はClaude Code MCP設定ガイドを参照してください。

claude_desktop_config.jsonとは何か

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

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

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

設定ファイルの場所

ファイルは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 に明示する必要があります。

パスは必ず絶対パスで書きます。Claude Desktopがどのディレクトリから起動されるかは環境依存です。./data のような相対パスは作業ディレクトリ次第で解決先が変わり、サーバーが見つからないエラーの典型的な原因になります。

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

claude_desktop_config.json に書けるのはローカルで起動するstdioサーバーだけです。インターネット上でホストされたリモートMCPサーバーに接続したい場合は、このファイルではなく設定画面の「Connectors」から「カスタムコネクターを追加」を使います。

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

リモートサーバーのURLを試しに claude_desktop_config.json へ書いても起動対象として認識されません。「リモートのMCPサーバーに繋がらない」と感じたら、まず設定ファイルではなく「Connectors」画面から追加できているかを確認します。

設定を反映させる手順

1. claude_desktop_config.json を保存する
2. Claude Desktopを完全に終了する(ウィンドウを閉じるだけでは常駐したままなので、メニューから「Quit」を選ぶ)
3. Claude Desktopを再起動する
4. チャット入力欄下部の「+」ボタンから「Connectors」を開き、登録したサーバー名とツールが表示されるか確認する

設定はアプリ起動時に一度だけ読み込まれます。ファイルを編集しただけでは反映されず、完全な再起動が必須です。サーバー定義を削除すればそのサーバーは次回起動時から立ち上がらなくなり、既存の会話に残っていたツール参照も無効になります。

よくあるつまずき

JSON構文エラー。カンマの付け忘れ・付け過ぎはこの手のファイルで最も起きやすいミスです。エディタのJSON構文チェックを通してから保存します。

相対パスを書いてしまう。args に渡すパスは絶対パスで統一します。~ はシェルでは展開されますが、JSON内の文字列としては展開されないため、/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": "..."
      }
    }
  }
}

サーバー名に使える文字がClaude Codeと違う。claude_desktop_config.json のサーバー名はスペースやピリオドを含められます。一方Claude Codeの claude mcp add-from-claude-desktop でインポートする際は、名前を英数字・ハイフン・アンダースコアのみに制限されます。それ以外の文字を含む名前はインポートできず、他のサーバーは正常にインポートされたままその名前だけスキップされます。Claude Desktopの設定をClaude Codeへ持っていく予定があるなら、最初からこの文字種でサーバー名を付けておくと手戻りがありません。

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

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

Windowsでは %APPDATA%\Claude\logs にログファイルが並びます。mcp.log にMCP接続全体のログが、mcp-server-{サーバー名}.log にサーバーごとの標準エラー出力が記録されます。

Claude CodeのMCP設定との違い

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

Claude Desktopですでに設定済みのサーバーがある場合、Claude Code側でゼロから書き直す必要はありません。claude mcp add-from-claude-desktop を実行すると対話形式で選んだサーバーをインポートできます。マルチクライアントで同じMCPサーバー群を使い回したいときに使う機能です。ただしこのコマンドはmacOSとWSL(Windows Subsystem for Linux)でのみ動作し、ネイティブのWindows環境では利用できません。スコープの使い分けや .mcp.json の書式はClaude Code MCP設定ガイドが対応します。MCPの仕組み自体から知りたい場合はMCPとは — AIと外部ツールをつなぐ標準プロトコルを参照してください。サーバーに繋がらない症状の切り分けは、Claude Code向けの記事ですが考え方は共通します。MCPサーバーに接続できないときの切り分け手順も参考にしてください。

よくある質問

claude_desktop_config.jsonの場所はどこですか

macOSは ~/Library/Application Support/Claude/claude_desktop_config.json です。Windowsは %APPDATA%\Claude\claude_desktop_config.json になります。手打ちで探すより、Claude Desktopの「Settings」→「Developer」→「Edit Config」から開くほうが確実です。ファイルが無ければこの操作で新規作成されます。

設定を保存したのにツールが出てきません

多くの場合、再起動が不完全です。ウィンドウを閉じただけではアプリが常駐したままなので、メニューから完全に終了してから起動し直します。それでも出ない場合はJSON構文エラーか絶対パスの誤りを疑い、ログファイルを確認します。

リモートのMCPサーバーもこのファイルに書けますか

書けません。claude_desktop_config.json はローカルで起動するstdioサーバー専用です。リモートサーバーは設定画面の「Connectors」から「カスタムコネクターを追加」してURLを登録し、OAuth等で認証します。

Desktop Extensionsなら設定ファイルの編集は不要になりますか

ディレクトリに公開されているサーバーや、.mcpb として配布されているサーバーを使うだけなら、設定ファイルを直接編集する必要はなくなります。自作サーバーやディレクトリ未収録のサーバーを動かす場合は、引き続き claude_desktop_config.json を編集するか、自分で .mcpb にパッケージングすることになります。

Claude CodeとMCPサーバーを共有できますか

設定ファイルは別物なので自動では共有されません。Claude Code側で claude mcp add-from-claude-desktop を実行すると、Claude Desktopの設定から選んでインポートできます。ただしこの機能はmacOSとWSL(Windows Subsystem for Linux)でのみ動作し、ネイティブのWindows環境では利用できません。また、サーバー名にスペースやピリオドを含む場合はインポートできないため、命名を英数字・ハイフン・アンダースコアに寄せておくと安全です。

まとめ

claude_desktop_config.json は、ディレクトリに無いローカルMCPサーバーを自分の手で登録するための設定ファイルです。場所はmacOSが ~/Library/Application Support/Claude/、Windowsが %APPDATA%\Claude\ です。いずれも設定画面の「Edit Config」から開けます。書き方は mcpServers の直下にサーバー名・command・args・env を並べるだけとシンプルですが、絶対パスの徹底と保存後の完全な再起動を忘れると動きません。公開済みのサーバーで済むならDesktop Extensionsのほうが手間は少なく済みます。Claude Codeでも同じサーバーを使いたい場合は、claude mcp add-from-claude-desktop でのインポートが近道です。