.mcp.json は「外部ツールの連絡先メモ」
Claude Code を触っていると、そのうち「MCP サーバーを追加したい」という話に出会います。そのときに登場するのが .mcp.json というファイルです。名前のとおり JSON 形式の設定ファイルで、中身はざっくり言うと「どの外部ツールを、どうやって起動して使うか」を書いたリストです。
例え話をすると、引っ越したばかりの家の冷蔵庫に貼ってある連絡先メモに近いです。「水道はここ、ガスはここ、宅配便はこの番号」と書いてあるから、何か必要になったときにその紙を見れば連絡できる。.mcp.json も同じで、Claude Code が「このプロジェクトから使える外部ツールって何があるんだっけ」と確認するための一覧なんですね。紙に書いていない業者には電話できないのと同じで、ここに書かれていないサーバーは Claude Code から使えません。
そもそも MCP って何だっけ
MCP(Model Context Protocol)は、AI と外部のツールやデータソースをつなぐための共通の決まりごとです。Claude Code 単体では、あくまで手元のファイルを読み書きしたりコマンドを実行したりするのが基本の守備範囲になります。そこに「MCP サーバー」という橋渡し役を足すと、その先にあるサービスやデータにも手が届くようになります。
USB に例えるとイメージしやすいかもしれません。USB という共通規格があるおかげで、マウスでもキーボードでも外付けドライブでも同じ差し込み口で使えます。MCP はその「共通の差し込み口」にあたる取り決めで、.mcp.json は「どの機器を差してあるか」を書いた台帳のようなものです。
どこに置くファイルなのか
ファイル名の先頭にドットが付いているとおり、これは隠しファイルの扱いです。プロジェクトのルート(リポジトリの一番上の階層)に .mcp.json を置くと、そのプロジェクトで作業するときの MCP サーバー設定として扱われます。
ここがポイントで、プロジェクトの中にファイルとして置けるということは、Git でバージョン管理できるということでもあります。チーム開発なら、リポジトリを clone した人全員が同じ MCP サーバー構成でスタートできる。「自分の環境では動くのに」問題が減るわけです。
中身のイメージ
細かい書き方はサーバーごとのドキュメントに従うのが確実ですが、雰囲気としては「サーバーの名前」をキーにして、その下に「起動コマンド」と「引数」を書く形になります。
{
"mcpServers": {
"example-server": {
"command": "npx",
"args": ["-y", "@example/mcp-server"]
}
}
}読み方は難しくありません。example-server という名前で呼ぶサーバーがあって、それは npx というコマンドで起動する、という宣言です。人間が電話帳に「実家:090-…」と書くのと同じ構造ですね。
初心者がつまずきやすいところ
まず単純ですが多いのが、JSON の文法ミスです。カンマが1つ多い、閉じ括弧が足りない、コメントを書いてしまった(JSON にコメントは書けません)。設定を足したのに何も起きないときは、まずファイルが正しい JSON になっているか疑ってみてください。
もう一つ気をつけたいのが、API キーなどの秘密情報を直接書き込まないことです。.mcp.json はリポジトリに commit できてしまうファイルなので、うっかりトークンをベタ書きすると、そのままチーム全体、場合によっては公開リポジトリに漏れます。認証情報の扱い方は各 MCP サーバーの案内を確認して、環境変数などを使う方法を選ぶのが安全です。
それから、設定ファイルを書き換えたあとは反映のために Claude Code を起動し直す必要がある場面があります。「書いたのに認識されない」と感じたら、一度セッションを終了して開き直してみるのが手っ取り早い確認方法です。
覚えておきたい距離感
最初のうちは .mcp.json を自分でゼロから書く機会はそう多くありません。使いたい MCP サーバーの公式ドキュメントに、そのままコピーできる設定例が載っていることがほとんどです。まずはそれを貼って動かし、動いたあとで「この command は何を実行しているんだろう」と中身を読み解く。この順番のほうが挫折しにくいと思います。
要するに .mcp.json は、Claude Code に「使っていい外部ツールはこれです」と教えるためのプロジェクト単位の名簿です。ここを理解しておくと、MCP まわりのトラブルシューティングがぐっと楽になります。
このページは役に立ちましたか？