「卒論のためにNotionと連携させようとしたのに、/mcpと打っても何も出てこない」「ゼミの共有リポジトリに設定を書いたはずなのに、自分のPCでしか動かない」——Claude Codeで研究資料やレポート作業を自動化しようとした大学生が、ほぼ必ず一度はぶつかる壁です。この記事では「MCP 設定 つまずき 繋がらない」で検索してたどり着いたあなたが、どこで詰まっているのかを切り分けて、最短で解決できるように整理します。
結論から言うと、繋がらない原因のほとんどは「書き方が間違っている」のではなく、記述先・スコープ・再起動・環境（特にWindows）のどれかがズレていることです。この記事では、実際に大学生がつまずきやすい「ゼミの共有リポジトリで動かない」「レポート作成中に急に切断される」という2つの具体的な場面を軸に、順番に潰していきます。
そもそもMCPとは何か：Claude Codeの「外部ツール接続口」
MCP（Model Context Protocol）は、Claude CodeがGitHubやNotion、Slack、データベースといった外部ツール・データソースと連携するための共通プロトコルです。たとえば卒論の資料をNotionでまとめている場合、Notion用のMCPサーバーを登録すると、Claude Codeから「先行研究をまとめたページを読んで、章立て案を作って」といった操作ができるようになります。ゼミの議事録やレジュメをGitHubで管理している人なら、リポジトリの内容を読ませて要約させる、といった使い方も可能です。
ここで初心者がつまずく第一歩が、「MCPサーバー」という言葉のイメージです。サーバーと聞くと大げさに感じますが、実態は外部ツールと話すための小さな仲介プログラムだと思ってください。これをClaude Codeに「登録」して初めて使えるようになります。逆に言えば、登録が正しく完了していなければ、いくら設定ファイルを眺めても繋がりません。
設定方法は2系統ある：ここが混乱の元
つまずきの大きな原因が、設定の入り口が複数あることです。古い記事と新しい記事で書き方がバラバラに見えるのも、このせいです。2026年時点では主に次の2つを使い分けます。
| 方法 | 書く場所 | 向いている場面 |
|---|---|---|
claude mcp add コマンド |
CLIで実行（内部で設定に書き込まれる） | 個人の卒論・研究用にサクッと登録したい |
.mcp.json |
プロジェクトのルートディレクトリ | ゼミやサークルの共有リポジトリで使いたい |
claude_desktop_config.json |
Claude Desktopアプリの設定ファイル | Desktopアプリ側で使いたい |
ここで最も多い誤解が「
claude_desktop_config.jsonに書けばClaude Code（CLI）でも動く」というもの。Desktopアプリ用とClaude Code（ターミナル）用は管理が別物です。CLIで使いたいならclaude mcp addか.mcp.jsonを使うのが基本だと覚えておきましょう。
まずはコマンドで登録するのが確実
迷ったら、設定ファイルを手書きするより claude mcp add から始めるのがおすすめです。タイポや配置場所のミスを減らせます。
# 基本構文
claude mcp add <名前> -- <実行コマンド> <引数...>
# 例：標準入出力(stdio)型のサーバーを登録
claude mcp add my-tool -- npx -y @example/mcp-server
# 登録できているか確認
claude mcp listclaude mcp list で名前が出てくれば、登録自体は成功しています。ここに出てこないなら、まだ「繋がる以前」の段階です。
ゼミやチームで共有したいなら.mcp.json
ゼミの共有リポジトリにコミットして、メンバー全員で同じMCPを使いたい場合は、プロジェクトルートに .mcp.json を置きます。ゼミの発表資料をNotionでまとめているケースを例にすると、こんな形です。
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_API_KEY": "secret_xxxxxxxxxxxx"
}
}
}
}command（実行コマンド）、args（引数）、env（APIキーなどの環境変数）の3点セットが基本構造です。APIキーが必要なツールで env を書き忘れると、登録はできても認証で弾かれて「繋がらない」状態になります。
スコープの違い：ここを間違えると「自分は動くのにゼミの仲間は動かない」
MCPには3つのスコープ（適用範囲）があります。これを理解していないと、実際によくあるのが「自分のPCでは卒論用のNotion連携が動くのに、同じリポジトリをクローンしたゼミの仲間の環境では何も出てこない」という状況です。
| スコープ | 適用範囲 | 共有されるか |
|---|---|---|
| local | 自分・そのプロジェクト内のみ | されない（個人用） |
| project | .mcp.json 経由でプロジェクト全体 |
される（ゼミ・チーム共有向け） |
| user | 自分の全プロジェクト | されない（横断・個人用） |
よくあるパターンが、ゼミのメンバーと共有したいのにスコープが local のままというケース。これだと設定が自分の手元にしか残らず、他のメンバーがリポジトリをクローンしても何も見えません。共有したいなら --scope project を指定して .mcp.json に書き出しましょう。
claude mcp add notion --scope project -- npx -y @notionhq/notion-mcp-server「繋がらない」を原因別に切り分ける
ここからが本題です。症状ごとに対処を分けます。実際にやってみると、上から順にチェックするだけで大半は解決します。
症状1：/mcp や claude mcp list に出てこない
- 再起動したかを確認。設定を追加・変更したら、Claude Codeを一度終了して立ち上げ直す必要があります。「書いたのに出ない」の半分はこれです。
claude mcp listで登録自体を確認。CLIに出ないなら設定ファイルの配置場所か記述形式が間違っています。- 設定ファイルが正しい場所にあるか確認。
.mcp.jsonはプロジェクトのルート（Claude Codeを起動したディレクトリ）に置く必要があります。卒論用のフォルダ構成で、資料フォルダの中にうっかり置いてしまい認識されない、というのが定番ミスです。 - JSONの構文エラーをチェック。末尾カンマや閉じ括弧の漏れがあると、ファイルごと無視されます。
症状2：登録はされているが起動に失敗する
/mcp でサーバー名は見えるのに「failed」と表示される場合は、実行コマンドそのものが動いていない可能性が高いです。設定に書いた command を、ターミナルで手動実行してみてください。
# 設定に書いたコマンドを単体で叩いてみる
npx -y @notionhq/notion-mcp-serverここでエラーが出るなら、Claude Codeの問題ではなくコマンドや依存パッケージ・APIキーの問題です。切り分けが一気に進みます。
症状3：レポート作成中や長時間処理で切断される
期末レポートのために大量の参考文献ページをまとめて読み込ませる、といった時間のかかる処理では、ツールがタイムアウトして落ちることがあります。公式ドキュメント上、HTTP/SSE型の接続では一時的な障害（5xxエラーやタイムアウト）に対して自動的にリトライを試みる仕組みが用意されています（回数や挙動はバージョンによって変わる可能性があるため、断定はできません）。
恒常的にタイムアウトするなら、タイムアウト値を延ばす環境変数を見直しましょう。
# 例：MCPツールのタイムアウトを延長（ミリ秒指定）
export MCP_TOOL_TIMEOUT=120000
# Claude Code起動時に効かせる
MCP_TOOL_TIMEOUT=120000 claude環境変数名や挙動、リトライ回数などの仕様は今後のアップデートで変わる可能性があります。2026年時点の対処法として、まずは1件だけの小さなリクエスト（論文1本だけ読ませる、など）で動作を確認し、問題なければ徐々に処理量を増やす、という進め方が安全です。公式ドキュメントの該当バージョンも合わせて確認してください。
環境別の落とし穴：特にWindows / Electron
設定が正しく見えるのに動かない場合、環境固有の問題を疑います。大学の共用PCや自宅のWindows PCでレポートを書いている人からの報告が多いのが、WindowsとElectron環境でのパス解決です。
- パスの区切り文字：JSON内でWindowsのパスを書くとき、バックスラッシュは
\\とエスケープが必要です。C:\\Users\\you\\toolのように二重にします。 - コマンドの実体：Windowsでは
npxがnpx.cmdとして解決される必要がある場合があります。動かないときはcmd /c npx ...の形を試すと通ることがあります。 - 絶対パス指定：相対パスで解決できないときは、実行ファイルやスクリプトを絶対パスで書くと確実です。研究室のPCなど、共有ドライブ経由で作業しているとこの問題が起きやすい傾向があります。
よくある誤解・NGパターン
- 「mcp devで動いたから完了」：開発用の
mcp devで動いても、実際にClaude Code（やDesktop）で動くとは限りません。最終的に使う環境で/mcpを確認するまでが検証です。 - 「Desktopの設定をCLIに流用」：前述のとおり管理が別。使う側（CLIかDesktopか）に合わせて設定先を選びます。
- 「再起動せずに直ったか確認」：設定変更後の再起動は必須。これを飛ばして「直らない」と判断しがちです。
- 「APIキーを直書きしてコミット」：ゼミの共有リポジトリに
.mcp.jsonをコミットする場合、APIキーをそのまま書くとリポジトリを見た全員に漏れてしまいます。就活で使うポートフォリオ用リポジトリを公開設定にしている人は特に注意が必要です。環境変数経由にするなどの配慮をしましょう。
FAQ
Q. claude mcp add と .mcp.json、どっちを使えばいい？
卒論や個人の研究用に自分だけで素早く使いたいなら claude mcp add、ゼミやサークルで共有したいなら --scope project 指定で .mcp.json に書き出す、が基本の使い分けです。
Q. /mcp を打っても無反応です
まず再起動、次に claude mcp list でCLI側の登録を確認してください。CLIにも出ないなら、設定ファイルの場所か構文に問題があります。
Q. 自分は使えるのにゼミのメンバーが使えません
スコープが local または user になっていないか確認を。共有には project スコープ（.mcp.jsonのコミット）が必要です。
Q. レポート作成中にしばらくすると勝手に切断されます
長時間処理によるタイムアウトの可能性があります。MCP_TOOL_TIMEOUT などのタイムアウト設定を見直し、まず小さなリクエストで挙動を確認してください。
まとめと次の一歩
Claude CodeでMCPが「繋がらない」とき、見るべき順番はシンプルです。
- 設定したら必ず再起動する
claude mcp listで登録自体を確認する.mcp.jsonがプロジェクトルートにあるか、JSON構文は正しいか- 実行コマンドを単体で叩いて、ツール側の問題を切り分ける
- ゼミやチームで共有が目的ならスコープを
projectに - Windowsならパスのエスケープとコマンド解決を疑う
この順で潰していけば、原因不明だった「繋がらない」が、たいてい「あ、再起動してなかった」「プロジェクトのルートに置いてなかった」といった具体的なミスに着地します。次の一歩としては、卒論やゼミの資料整理で使っているNotionやGitHubなど1つだけMCPを登録して /mcp で確認するところから始めてみてください。1つ通せば、2つ目以降は同じ手順の繰り返しです。
コメント