付録C　設定ファイルの場所とトラブル

📖 MCPサーバーを作って学ぶ AIに道具を持たせる入門 — はじめに・目次 ← 目次に戻る このページは読み物ではなく、道具箱です。上から順に読む必要はありません。動かなくなったときに開いて、当てはまるところだけを見てください。

---

🗺 このページの使い方 🟢

困っている内容から、直接飛んでください。

こんなとき	どこを見る
設定ファイルがどこにあるか分からない	1. 場所
開き方が分からない・ファイルが無い	2. 開き方
何をどう書けばいいか分からない	3. 書式
設定したのにサーバーが出てこない	5. トラブル早見表
ログを見たい	6. ログを見る
ちゃんと繋がっているか確認したい	7. 繋がっているか確認する
第2章の天気サーバーがどうしても動かない	8. 救済措置

---

1. 設定ファイルの場所 🟢

Claude Desktop に「どのMCPサーバーを起動するか」を教えるファイルは、たった1つです。名前は claude_desktop_config.json。

OS	場所
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%AppData%\Claude\claude_desktop_config.json

💡 ~ は「あなたのホームフォルダ」の意味です（macOS なら /Users/あなたの名前）。%AppData% は Windows の「アプリの設定置き場」を指す書き方で、実際には C:\Users\あなたの名前\AppData\Roaming あたりです。

ファイルが無くても、あわてないでください。 最初は存在しないのが普通です。無ければ自分で作ります。

---

2. 開き方（ファイルが無ければ自分で作る） 🟢

方法A：Claude Desktop の画面から開く（いちばん確実）

1. Claude メニュー（macOS なら画面いちばん上のメニューバー。Claude のウィンドウの中の設定ではありません）から「Settings…」を開く
2. 左のサイドバーの「Developer」タブを開く
3. 「Edit Config」ボタンを押す

これでファイルが無ければ新しく作られ、あれば開かれます。場所を自分で掘らなくていいので、初回はこれがおすすめです。

方法B：エディタで直接開く

VS Code が入っているなら、ターミナル（Windows は PowerShell）でこれを打ちます。

macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows（PowerShell）:

code $env:AppData\Claude\claude_desktop_config.json

⚠️ macOS のコマンドにある Application\ Support のバックスラッシュ \ を消さないでください。フォルダ名にスペースが入っているので、「ここは区切りじゃなくて名前の一部だよ」とターミナルに教えるための記号です。消すと Application と Support が別物として扱われて失敗します。

ファイルが存在しない場合、code は空のファイルを開いてくれます。そこに書いて保存すれば、それがそのまま設定ファイルになります。

---

3. 書式の全体像 🟢

中身は JSON という形式です。全体はこういう入れ子になっています。

{
  "mcpServers": {
    "サーバーの名前": {
      "command": "起動するコマンド",
      "args": ["コマンドに渡す引数", "…"],
      "env": { "環境変数名": "値" }
    }
  }
}

それぞれの意味

キー	意味	例
mcpServers	この中に全サーバーを並べる、いちばん外側の箱	—
サーバーの名前	あなたが決める呼び名。Claude の画面にこの名前で出る	memo
command	実際に起動するプログラム	node
args	command に渡す引数。配列（[ ]）	["/絶対パス/build/index.js"]
env	サーバーに渡したい環境変数（省略可）	{ "NOTES_DIR": "/絶対パス/notes" }

つまり Claude Desktop は、起動時に裏で node /絶対パス/build/index.js を実行しているだけです。特別な魔法はありません。

第5章のメモサーバーを書くとこうなる

{
  "mcpServers": {
    "memo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/memo/build/index.js"],
      "env": { "NOTES_DIR": "/ABSOLUTE/PATH/TO/notes" }
    }
  }
}

/ABSOLUTE/PATH/TO/ の部分は、あなたのパソコンの本当のパスに置き換えてください。調べ方は後述します。

複数のサーバーを並べる

サーバーは何個でも並べられます。mcpServers の中に、カンマ区切りで足していくだけです。

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/あなた/projects/weather/build/index.js"]
    },
    "memo": {
      "command": "node",
      "args": ["/Users/あなた/projects/memo/build/index.js"],
      "env": { "NOTES_DIR": "/Users/あなた/notes" }
    }
  }
}

💡 "weather" の閉じカッコ } のうしろにカンマが要るのがポイントです。JSON では「まだ次があるよ」の合図がカンマ。逆に最後の項目のうしろにカンマを付けてはいけません（後述）。

---

4. 3大原則（ここを外すとまず動きません） 🟢

原則①：パスは絶対パスで書く

./build/index.js のような相対パス（今いる場所からの道順）は使えません。必ず /Users/… から始まる絶対パス（フルの住所）で書いてください。

なぜか。 Claude Desktop があなたのサーバーを stdio（標準入出力）で起動するとき、そのプログラムの「今いる場所」＝カレントディレクトリは決まっていないからです。公式ドキュメントも「クライアントの設定から起動されたサーバーの作業ディレクトリは未定義かもしれない（macOS では / のことがある）」と明記しています。

「今いる場所」が分からないのに「ここから見て ./build」と言っても、どこを指すか誰にも分かりません。だから住所を全部書く必要があります。

絶対パスの調べ方（プロジェクトのフォルダで実行）:

# macOS / Linux
pwd

# Windows（コマンドプロンプト）
cd

出てきた文字列に /build/index.js を足したものが、args に書くパスです。

💡 これは .env ファイルの中身も同じです。設定に書くパスは全部絶対パスにしておくと安全です。

原則②：環境変数は自動では引き継がれません

ターミナルで export NOTES_DIR=/Users/あなた/notes と設定してから Claude Desktop を起動しても、サーバーには届きません。

stdio で起動されるMCPサーバーが自動的に受け継ぐ環境変数は、ごく一部だけです（どれが引き継がれるかは OS によって違います）。あなたが渡したい値は、env キーで明示的に書くしかありません。

"env": { "NOTES_DIR": "/Users/あなた/notes" }

APIキーなども同じで、env に書かないとサーバー側では「未設定」になります。第5章で NOTES_DIR が読めない、というトラブルの正体はたいていこれです。

原則③：変えたら完全終了して再起動

設定ファイルを保存しただけでは、何も変わりません。Claude Desktop は起動時にしか設定を読まないからです。

⚠️ ウィンドウを閉じるだけでは足りません。 macOS ではウィンドウを閉じてもアプリは生きています（メニューバーに残っています）。

正しい終わらせ方:

• macOS: Cmd + Q（またはメニューの Claude → Quit Claude）→ もう一度起動
• Windows: ウィンドウを閉じるだけでなく、タスクトレイのアイコンからも終了させる → もう一度起動

公式ドキュメントもはっきり書いています。設定を変えたときも、サーバーのコードを変えたときも、「完全に終了して開き直す。ウィンドウを閉じるだけでは不十分」です。

💡 サーバーのコードを直したときは、再起動の前に npm run build も忘れずに。Claude Desktop が読むのは src/index.ts ではなく、ビルドしてできた build/index.js のほうです。

---

5. トラブル早見表 🟢

症状	原因	対処
サーバーが Claude にまったく出てこない	設定を変えたあと再起動していない	完全終了して再起動（Cmd + Q / タスクトレイから終了）
サーバーが出てこない	JSONの書式ミス。書式が壊れていると設定ファイルまるごと無視されます	末尾カンマ・コメント・閉じカッコを確認（下の「JSONの落とし穴」）
サーバーが出てこない	args のパスが相対パス、または綴り違い	絶対パスに直す。pwd で確認
サーバーが出てこない	npm run build を忘れて build/index.js が無い	プロジェクトで npm run build を実行
ログに Cannot find module	パスが間違っている／node_modules が無い	パスを確認。npm install を実行
ログに ENOENT	command のプログラムが見つからない	which node（Windows は where node）で場所を調べ、command にフルパスを書く
起動した直後に落ちる	サーバーが stdout に文字を出している（console.log）	console.error に変える。→ 第3章
ツールが一覧に出るのに呼ばれない	説明文（description）が曖昧でAIが気づかない	説明文を具体的に書き直す。→ 第5章
環境変数が undefined になる	ターミナルで export しても引き継がれない	設定の env キーに書く（原則②）
Windows でパスのエラーが出る	バックスラッシュが1本	\\ と2本にする、または / を使う
何度直しても直らない	そもそもサーバー単体で動いていない	ターミナルで node /絶対パス/build/index.js を直接実行してみる。→ 第4章

---

JSONの落とし穴（初心者が確実に踏む3つ）

① 末尾のカンマ（トレイリングカンマ）はエラー

{
  "mcpServers": {
    "memo": {
      "command": "node",
      "args": ["/Users/you/memo/build/index.js"],   ← ✗ 最後の項目のうしろにカンマ
    }
  }
}

JavaScript では許されますが、JSON では許されません。「最後の項目のうしろにカンマは付けない」と覚えてください。

② コメントは書けない

{
  // メモサーバー   ← ✗ これがあるだけで全部読めなくなります
  "mcpServers": { }
}

// も /* */ も JSON には存在しません。メモを残したいなら、使わないサーバー名を "_memo_無効化中" のように変えて残す、といった逃げ方をします。

③ Windows のバックスラッシュは \\ にエスケープする

JSON の文字列の中で \ は「特別な意味の始まり」です。そのまま1本書くと壊れます。

"args": ["C:\Users\you\memo\build\index.js"]     ← ✗ 壊れる
"args": ["C:\\Users\\you\\memo\\build\\index.js"] ← ✓ 2本にする
"args": ["C:/Users/you/memo/build/index.js"]      ← ✓ スラッシュでもOK

公式も「Windows ではダブルバックスラッシュ（\\）かフォワードスラッシュ（/）を使うこと」と書いています。迷ったら / のほうが事故が少ないです。

💡 書式が合っているかの確かめ方：VS Code でファイルを開くと、壊れている箇所に赤い波線が出ます。それだけで9割見つかります。

---

6. ログを見る 🟢

「サーバーが出てこない」の本当の理由は、ログに書いてあります。推測で直す前に、まずログを見てください。

OS	場所
macOS	~/Library/Logs/Claude
Windows	%APPDATA%\Claude\logs

このフォルダには2種類のファイルがあります。

• mcp.log … MCP接続全般のログ。繋がらなかった理由はここ
• mcp-server-サーバー名.log … そのサーバーが stderr（標準エラー出力）に吐いたもの。あなたの console.error はここに出ます

流れるログをリアルタイムで眺める

macOS:

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

Windows（PowerShell）:

type "$env:AppData\Claude\logs\mcp*.log"

💡 tail は「ファイルの末尾を見る」コマンド、-F は「新しく増えた行を追いかけ続ける」オプションです。macOS ならこれを流したまま Claude Desktop を再起動すると、接続の様子が目の前で流れます。これが最強のデバッグ方法です（Windows の type は追いかけずに、その時点の内容を表示します）。

ログに出るのは主に、接続イベント／設定の問題／実行時エラー／やりとりされたメッセージです。詳しい読み方は 第4章　デバッグの作法 — 見えない通信を覗く にあります。

---

7. 繋がっているか確認する 🟢

設定して再起動したら、Claude の画面で確かめます。

1. チャットの入力欄の左下にある「Add files, connectors, and more」の プラスアイコン（＋） をクリック
2. 「Connectors」にマウスを合わせて、「Manage connectors」をクリック
3. コネクタの一覧が出ます。自分のサーバー名（例：filesystem）を選ぶと、そのサーバーが出しているツールの一覧が見られます

ここに自分のサーバー名が出ていれば成功です。出ていなければ、まだ繋がっていません（→ 5. トラブル早見表）。

⚠️ 「＋」ボタン自体は、MCPサーバーが1つも設定されていなくても出ます。 ファイル添付なども兼ねた汎用のメニューだからです。だから「＋があるから設定は読めているはず」とは判断できません。確かめるべきは Manage connectors の一覧に自分のサーバー名があるかどうか、それだけです。名前が無いなら設定ファイルかサーバー起動のどちらかで失敗しているので、ログ（→ 6. ログを見る）を見てください。

📖 画面つきの手順は公式の Connect to local MCP servers にあります。UIは更新されることがあるので、食い違ったら公式を信じてください。

---

8. 「第2章の天気サーバーがどうしても動かない」とき 🟢

ここが、このページでいちばん大事なところです。

第2章の天気サーバーは、アメリカ政府の気象API（api.weather.gov）を呼びます。つまり——あなたのパソコンの外側に依存しています。

だから、あなたのコードが完璧でも動かないことがあります。

• API側が一時的に落ちている・重い
• APIの仕様が変わった（教材が書かれた後に変わることがあります）
• 会社や学校のネットワークが外部への通信を止めている
• プロキシやファイアウォールに阻まれている
• そもそも米国内のデータしか無い（「東京の天気」は仕様として出ません。これは第2章の狙いどおりの挙動です）

このうちあなたに直せるものは1つもありません。ここで何時間も溶かすのは、まったくの無駄です。

🆘 結論：第2章は飛ばして、第5章に進んでかまいません

どうしても天気サーバーが動かないなら、第2章はいったん諦めて、第5章　自分の道具を作りはじめる — メモを検索する に進んでください。

第5章のメモサーバーは、外部APIに一切依存しません。 自分のパソコンの中のファイルを読むだけです。ネットワークもAPIキーもいりません。だから確実に動きます。

第2章は「他人の完成品が動くところをまず見る」ための章であって、教材の必須部品ではありません。ここで詰まって先に進めなくなるくらいなら、自分のサーバーを作りはじめるほうが、はるかに学びが多いです。

飛ばす前に、これだけは持っていってください

第2章から先の章が前提にしている「持ち帰り」は、実は3つだけです。天気サーバーが動かなくても、この3つを読んで頭に入れておけば、第5章以降はすべて理解できます。

1. 設定ファイルの書き方（mcpServers / command / args / env）← このページの 3. で足ります
2. 絶対パス・完全再起動・npm run build の3点セット ← このページの 4. で足ります
3. 💡 AIが読んでいるのは「説明文」だけ、という気づき ← 下で説明します

3つめだけ補足します。第2章では、天気サーバーの get_alerts というツールの説明文に「Two-letter state code（2文字の州コード）」と書いてあるのを見てもらう予定でした。「東京の天気」が出ないのは、サーバーが壊れているからではなく、その道具がそもそも米国の州しか受け取れないからです。そしてAIは、その説明文だけを頼りに「東京は州コードじゃないな」と判断しています。

つまり——道具にできないことは、AIにもできません。 そしてAIが道具について知っているのは、あなたが書いた説明文だけです。この一文さえ握っていれば、第2章を動かさなくても損はありません。第5章・第6章で、今度は自分の書いた説明文で、これをたっぷり体験してもらいます。

あとで戻ってきてもいい

第5章まで進むと、あなたはMCPサーバーの仕組みを自分の手で理解しているはずです。その状態で第2章に戻ると、動かない理由が自分で切り分けられるようになっています。天気サーバーは、そのときの練習台にしてください。

💡 教材で詰まったら飛ばす、は正しい進み方です。順番に完璧をやろうとして止まるより、動くものを1つ作ってから戻るほうが、結局は速く着きます。

---

📗 ことばメモ

ことば	よみ	意味
絶対パス	ぜったいパス	/Users/… のように、いちばん上から書いたファイルの住所。設定ファイルではこれ必須
相対パス	そうたいパス	./build のように「今いる場所から見た」道順。設定ファイルでは使えない
カレントディレクトリ	—	プログラムから見た「今いる場所」。MCPサーバーでは未定義のことがある
環境変数	かんきょうへんすう	プログラムに外から渡す設定値。MCPでは env キーで明示的に渡す
JSON	ジェイソン	設定ファイルの書式。コメント不可・末尾カンマ不可
エスケープ	—	特別な意味を持つ文字を「ただの文字」として書くこと。JSONでは \ を \\ と書く
stderr	標準エラー出力	ログを出す安全な口。console.error の行き先。mcp-server-*.log に残る
完全終了	—	ウィンドウを閉じるだけでなく、アプリのプロセスごと終わらせること（Cmd + Q など）

---

➡️ 次へ

このページは場所と書式の話でした。エラーメッセージそのものから原因を引きたいときは、もう1つの道具箱があります。

付録D　よくあるエラー集 — 「この文言が出たら、原因はこれ」の対応表です。

切り分けの手順そのものを身につけたい人は、第4章　デバッグの作法 — 見えない通信を覗く に戻ってください。このページで直らないものは、たいてい第4章の手順で見つかります。

関連ページ

• MCPサーバーを作って学ぶ AIに道具を持たせる入門 — はじめに・目次 — 目次
• 第2章　まず公式のサンプルを動かす — 天気サーバーをClaudeに繋ぐ — 設定ファイルの初登場はここ
• 第4章　デバッグの作法 — 見えない通信を覗く — 切り分けの手順
• 第5章　自分の道具を作りはじめる — メモを検索する — 外部APIに依存しない、確実に動く章
• 付録D　よくあるエラー集 — エラー文言から引く