claude mcp add で詰まった3箇所 — ドキュメント通りに打ったのに動かなかった実設定ガイド

claude mcp add のドキュメントは短い。コマンドの形式と引数の説明はあるが、「実際に打ったら動かなかった」場面の説明はほぼない。

2026-06-17、ラッコキーワードMCP（月2,475円）を Claude Code に接続したとき、3 箇所で手が止まった。どこで止まったか、なぜ止まったか、どう抜けたかを記録する。

---

結論

claude mcp add で動かなかった3箇所を先にまとめる。

詰まり	原因	対処
①<command>に何を書くか不明	claude 側ドキュメントには書いていない	MCP 提供元の README を見る
②--key VALUE系引数がエラーになる	ハイフン付き引数が claude のオプションと混在する	-- セパレータを挿入する
③別プロジェクトで MCP が消えた	スコープ無指定 = プロジェクトローカル	--scope global を付けて再追加

---

この記事の前提

• 環境: Claude Code（CLI）、ターミナル操作
• 接続した MCP: ラッコキーワードMCP（月2,475円）
• 動機: KW 調査を手動でやり続けると継続できない → Claude Code に流し込んで展開を自動化したかった
• 実施日: 2026-06-17

MCP の概念整理（いつ MCP を使うか）は別記事で扱っている。本記事は「実際に打ったら動かなかった」場面の記録に絞る。

---

詰まった3箇所

詰まり①：<command> に何を書くか、claude 側のドキュメントには載っていない

claude mcp add <name> <command> のシンタックスはすぐわかる。問題は <command> に何を書くかだ。

公式ドキュメントには「MCP サーバーを起動するコマンド」と書いてあるが、ラッコキーワードMCPを接続するとき「起動コマンドって何？」が分からなかった。Claude Code 側の --help を見ても文法の説明しかない。

原因: <command> の中身は MCP ごとに違う。Claude Code のドキュメントは「任意の起動コマンドを受け取る」ことだけ説明していて、接続先 MCP の起動方法は提供元の問題だから書いていない。

対処: 接続したい MCP の公式 README を見る。ラッコキーワードMCPの場合、セットアップページに Claude Code 向けの起動コマンドが記載されていた。そこに書いてある内容をそのまま <command> 以降に貼る。

---

詰まり②：引数にハイフンが含まれると、-- セパレータが要る

公式 README に書いてある起動コマンドを claude mcp add rakko-keyword の後ろに続けて打ったところ、ハイフンから始まる引数（例: --env KEY=VALUE や --api-key <値>）を claude コマンドのオプションとして誤認識するケースがあった。

エラーメッセージはコマンドオプション系のものが出るが、「なぜコマンド自体のエラーが出るのか」が最初わからなかった。

原因: --key VALUE の形式が claude mcp add のオプションとして解釈される。シェルの引数解析の問題で、MCP 側の引数が claude コマンド側に混入する。

対処: claude mcp add の name と起動コマンドの間に -- を入れる。

# NG: --api-key が claude mcp add のオプションとして誤認識される場合がある
claude mcp add rakko-keyword <command> --api-key <値>

# OK: -- を挿入して引数の境界を明示する
claude mcp add rakko-keyword -- <command> --api-key <値>

引数にハイフンが含まれない単純な npx コマンド などは -- なしで通ることもある。起動コマンドに -- や - 付き引数が含まれる場合は -- を入れる、と覚えておくと安全。

---

詰まり③：スコープ無指定で追加すると、別プロジェクトでは「見えない」

追加直後は claude mcp list にラッコキーワードMCPが表示されていた。ところが別のディレクトリで Claude Code を起動すると、MCP の一覧に出てこない。

「設定が消えた」と思ったが、消えていなかった。

原因: claude mcp add はスコープを指定しないとプロジェクトローカル（その作業ディレクトリ限定）で追加する。別のプロジェクトディレクトリに移動すれば見えなくなるのは仕様通り。

設定ファイルの保存先がスコープで変わる：

スコープ	保存先
プロジェクトローカル（デフォルト）	{プロジェクトルート}/.claude/mcp.json
グローバル	~/.claude/mcp.json

対処: 全プロジェクトで使う MCP は最初から --scope global で追加する。すでにローカルで追加してしまった場合は claude mcp remove <name> で削除してから --scope global 付きで再追加する。

# グローバルで追加し直す手順
claude mcp remove rakko-keyword
claude mcp add --scope global rakko-keyword -- <起動コマンド>
claude mcp list  # グローバルスコープに移ったか確認

ラッコキーワードは「どの記事作業でも使いたい」と判断してグローバルで再設定した。

---

原因のパターンまとめ

3 つの詰まりに共通しているのは「Claude Code 側のドキュメントを読んでも解決しない」点だ。

• ①は MCP 提供元の問題
• ②はシェルの引数解析の問題
• ③はデフォルト値が明示されていない問題

どれも claude のドキュメントを深掘りしても答えがない。「MCP 提供元の README を見る」「引数にハイフンがあれば -- を挿入する」「スコープはデフォルトがローカルだと覚える」の 3 点を知っていれば詰まらずに進める。

---

今日やること（3 つ以内）

1. 接続したい MCP の公式 README を開き、Claude Code 向けの起動コマンドを確認する
2. 起動コマンドにハイフン付き引数があれば claude mcp add <name> -- <command> の形にする
3. 全プロジェクトで使う MCP は --scope global を付けて追加し、claude mcp list で確認する

---