2026年10月18日 / 最終更新日 : 2026年10月18日ふじながただしコラム

Claude CodeのMCP設定方法｜claude mcp addの使い方・.mcp.json・スコープと接続確認

Q: Claude CodeでMCPサーバーを追加するコマンドは？

リモートのサーバーはclaude mcp add --transport http 名前 URL、手元で動かすサーバーはclaude mcp add 名前 -- 起動コマンドです。JSONで設定がある場合はclaude mcp add-json 名前 'JSON'も使えます。

Q: Claude CodeのMCP設定ファイルはどこにありますか？

localとuserスコープはホームディレクトリの~/.claude.json、projectスコープはプロジェクト直下の.mcp.jsonに保存されます。チームで共有したいときは--scope projectで追加して.mcp.jsonをコミットします。

Q: すべてのプロジェクトで同じMCPサーバーを使うには？

--scope userを付けて追加します。例：claude mcp add --transport http hubspot --scope user URL。既定のlocalスコープだと、追加したプロジェクトでしか使えません。

Q: MCPサーバーを削除・一時停止するには？

削除はclaude mcp remove 名前です。設定を残したまま止めたいときは、Claude Codeの中で/mcpを開いてそのサーバーをオフにします。

Q: MCPサーバーにつながらないときは？

claude mcp get 名前で状態を確認し、認証が必要なら/mcpかclaude mcp login 名前でログインします。stdioのサーバーは、--より後ろの起動コマンドをターミナルで単独で動かして、エラーが出ないか確かめます。

Claude CodeにMCPサーバーを追加するには、ターミナルで claude mcp add コマンドを使います。リモートのサーバーなら「claude mcp add –transport http 名前 URL」、手元で動かすサーバーなら「claude mcp add 名前 — 起動コマンド」と書き、追加後は claude mcp list か、Claude Codeの中で /mcp を開いて接続を確認します。

この記事は、Claude CodeでMCPを「設定して使う」ための手順書です。コマンドの書き方、3つのスコープ（local・project・user）と.mcp.jsonの書き方、接続の確認と削除、つながらないときの切り分け、権限の絞り方を、Claude Code公式ドキュメント「Connect Claude Code to tools via MCP」に沿ってまとめました（2026年10月18日確認）。MCPという規格そのものの仕組みはMCPサーバーとは？、どのサーバーを入れるかはClaude Code MCPサーバーおすすめ一覧で解説しています。

Claude CodeのMCPとは：外部ツールをつなぐ差し込み口

MCP（Model Context Protocol）は、AIアプリと外部のツールやデータをつなぐための公開された規格です。Claude Codeはこの規格の「クライアント」になっていて、MCPサーバーを追加すると、そのサーバーが持つ機能（ツール）をClaude Codeが呼び出せるようになります。公式ドキュメントでは、課題管理ツールの内容から機能を実装してGitHubにプルリクエストを出す、データベースに問い合わせる、Figmaのデザインに合わせてテンプレートを直す、といった使い方が例に挙がっています。

MCPは必須ではありません。ファイルの読み書き、コマンドの実行、Gitの操作はMCPなしでもできます。Claude Codeの外にある情報やサービスを使わせたいときに足すものと考えてください。

claude mcp add の書き方（3つのパターン）

公式ドキュメントの書き方を、接続方法（トランスポート）別にまとめます。

接続方法	使う場面	コマンドの形
HTTP（推奨）	クラウドで動いているリモートのサーバー	`claude mcp add --transport http 名前 URL`
stdio	自分のPCでプロセスとして動かすサーバー	`claude mcp add 名前 -- 起動コマンド引数`
SSE（非推奨）	SSEしか用意していない古いサーバー	`claude mcp add --transport sse 名前 URL`

リモートのサーバーを追加する（HTTP）

# 書き方
claude mcp add --transport http <名前> <URL>

# 例：Notionにつなぐ（公式ドキュメントの例）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 例：トークンをヘッダーで渡す
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

公式ドキュメントは、リモートのサーバーにはHTTPを使うよう案内しています。SSEは非推奨（deprecated）と明記されており、v2.1.265以降は--transport httpで追加すればSSEしか受け付けないサーバーにも自動で切り替えてつなぎます。

手元で動かすサーバーを追加する（stdio）

# 書き方
claude mcp add [オプション] <名前> -- <コマンド> [引数...]

# 例：APIキーを環境変数で渡してnpxで起動する（公式ドキュメントの例）
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

ポイントは--（ハイフン2つ）です。--より前はClaude Code自身のオプション（--transport、--env、--scope）、後ろはサーバーを起動するコマンドとして、そのまま渡されます。--を忘れると、サーバー側のオプション（たとえば--port）をClaude Codeが自分のオプションとして読もうとして失敗します。

もう1つ、--envの直後にサーバー名を書くと、名前も「KEY=value」の続きとして読まれてエラーになります。上の例のように、--envと名前のあいだに--transport stdioなどのオプションを挟みます。

JSONで追加する（claude mcp add-json）

サーバーの説明書に設定がJSONで書かれている場合は、claude mcp add-jsonでそのまま登録できます。

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Claude Desktop向けの説明書にある"mcpServers": { ... }のブロックを使うときは、外側のmcpServersを外し、中身の1件分だけを渡します。また、urlがあるのにtypeがない設定は、Claude Codeがstdioのサーバーと読んでしまい、エラーで読み飛ばされます。リモートなら"type": "http"を必ず書きます（streamable-httpと書いても同じ意味として受け付けます）。

Claude Desktopの設定を取り込む

Claude DesktopでMCPサーバーを設定済みなら、claude mcp add-from-claude-desktopで一覧から選んで取り込めます。公式ドキュメントでは、この機能はmacOSとWSL（Windows Subsystem for Linux）でだけ動くとされています。名前に空白などを含むサーバーは取り込めません（使える文字は英数字・ハイフン・アンダースコア）。

スコープ：local・project・userの違い

どの範囲で使うサーバーかを--scopeで決めます。指定しなければlocalです。

スコープ	使える範囲	チームと共有	保存先
local（既定）	追加したプロジェクトだけ	しない	`~/.claude.json`（そのプロジェクトの欄）
project	そのプロジェクトだけ	する（Gitで共有）	プロジェクト直下の`.mcp.json`
user	自分のすべてのプロジェクト	しない	`~/.claude.json`

# このプロジェクトだけで自分だけが使う（既定）
claude mcp add --transport http stripe https://mcp.stripe.com

# チームで共有する → .mcp.json に書かれる
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# どのプロジェクトでも使う
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

同じ名前のサーバーが複数のスコープにあるときは、local → project → userの順で優先され、優先されたほうの設定がまるごと使われます（項目ごとに混ぜ合わせはしません）。「設定を直したのに反映されない」ときは、別のスコープに同じ名前が残っていないかを確かめます。

なお、MCPのlocalスコープの保存先はホームディレクトリの~/.claude.jsonで、プロジェクト内の.claude/settings.local.jsonとは別物です。名前が似ているので混同しないようにしてください。

.mcp.jsonの書き方とトークンの隠し方

projectスコープで追加すると、プロジェクト直下に次の形の.mcp.jsonができます。手で書いてコミットしてもかまいません。

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

.mcp.jsonはGitで共有するファイルなので、APIキーを直接書くのは避けます。${変数名}と書くと、各自の環境変数の値に置き換わります。${変数名:-既定値}で、変数がないときの値も決められます。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

置き換えが使えるのはcommand・args・env・url・headersです。ただし、リモートサーバーのurlとheadersでは、ANTHROPIC_API_KEYなどClaude Code自身やクラウドの認証情報にあたる変数は、意図せず外部に送らないよう空として扱われます。サーバー用のキーはAPI_KEYのような自分で決めた名前の変数に入れてください。

セキュリティのため、他人がコミットした.mcp.jsonのサーバーは、対話モードで初めて起動したときに使ってよいか確認が出ます。承認をやり直したいときはclaude mcp reset-project-choicesを実行します。

接続を確認する・一時停止する・削除する

claude mcp list          # 登録済みサーバーと状態の一覧
claude mcp get notion    # 1つのサーバーの詳細
claude mcp remove notion # 削除
/mcp                     # Claude Codeの中で状態を見る・認証する・オンオフする

claude mcp listには、サーバーごとに次のような状態が表示されます。

表示	意味	すること
✔ Connected	つながっている	そのまま使える
! Needs authentication	ログイン（OAuth）が必要	`/mcp`で認証するか、`claude mcp login 名前`
✘ Failed to connect	つなげなかった	URL・コマンド・トークンを確認（次の章）
⏸ Pending approval	.mcp.jsonのサーバーをまだ承認していない	`claude`を対話モードで起動して承認

設定を消さずに一時的に止めたいときは、/mcpの画面でそのサーバーをオフにします。リモートのサーバーをclaude mcp removeで削除すると、保存されていたOAuthのトークンも一緒に消えます。

MCPサーバーにつながらないときの切り分け

まず claude mcp get 名前 で状態を見る。claude mcp addは設定を書き込むだけで、トークンが正しいかまでは確かめません。追加できても、つながるとは限りません
401などのエラーなら認証を疑う。トークンの期限切れや、環境変数が空になっていないかを確認します
stdioなら、--より後ろのコマンドをターミナルで単独で実行してみる。Node.jsやPythonが入っていない、パッケージ名の打ち間違いなど、サーバー側の起動失敗が多い原因です
起動が遅いサーバーは待ち時間を延ばす。環境変数MCP_TIMEOUTで起動の待ち時間を変えられます（例：MCP_TIMEOUT=10000 claudeで10秒）
失敗したサーバーをつなぎ直す。/mcp reconnect allで、失敗または認証待ちのサーバーをまとめて再接続できます（v2.1.284以降）
同じ名前が別のスコープにないか確かめる。優先順位はlocal → project → userです

MCPのツールが大量の結果を返すと、Claude Codeは1万トークンを超えたところで警告を出し、既定では2万5,000トークンを上限として、超えた結果はファイルに保存して扱います。上限は環境変数MAX_MCP_OUTPUT_TOKENSで変えられます。

MCPツールの権限を絞る

MCPのツールは、Claude Codeの権限設定（settings.jsonのpermissions）で、mcp__サーバー名__ツール名という名前で許可・拒否を書けます。公式の権限ドキュメントによると、書き方は次のとおりです（2026年10月18日確認）。

書き方	対象
`mcp__github__*`	githubサーバーのすべてのツール
`mcp__github__get_*`	githubサーバーのget_で始まるツール
`mcp__github__create_issue`	1つのツールだけ
`mcp__*`（deny・askのみ）	すべてのMCPツール

読み取り系のツールだけを許可し、書き込みや削除をするツールは毎回確認（ask）にしておくと、意図しない操作を防げます。サーバー名に.や空白が含まれる場合は_に置き換えて書きます。権限設定全体の書き方はClaude Codeの権限設定で詳しく説明しています。

また、公式ドキュメントは、つなぐ前にそのサーバーを信頼できるか確かめるよう警告しています。外部のWebページなどを読み込むサーバーは、その中に仕込まれた指示（プロンプトインジェクション）の入り口になり得るためです。データベースにつなぐ例でも、読み取り専用のユーザーで接続するよう案内されています。

例：GitHubのMCPサーバーを追加して使う

公式ドキュメントの例では、GitHubの設定画面でfine-grainedの個人アクセストークンを作り、ヘッダーで渡して追加します。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

追加したら/mcpでgithubの行にチェックマークが付いているかを確認し、Claude Codeに「PR #456をレビューして改善点を挙げて」「いま見つけたバグのissueを作って」のように頼みます。トークンには、Claudeに触らせたいリポジトリだけの権限を付けるのが安全です。GitHub Actionsから動かす方法はClaude Code GitHub連携の方法で扱っています。

知っておくと便利な機能

@でリソースを参照：プロンプトで@を打つと、ファイルと並んでMCPサーバーのリソースが候補に出ます（例：@github:issue://123）
MCPのプロンプトをコマンドとして使う：サーバーが用意したプロンプトは、/を打つとコマンドとして一覧に出ます
ツール検索：起動時にはツールの名前だけを読み込み、定義は必要になったときに読み込むので、サーバーを増やしてもコンテキストを圧迫しにくい仕組みになっています
claude.aiのコネクタ：claude.aiのアカウントでログインしている場合、claude.aiで追加したコネクタもClaude Codeから使えます

Claude Codeのコマンド全体はClaude Code コマンド一覧、CLAUDE.mdなどの設定ファイルの使い分けはClaude Code の各種 MDファイル完全活用ガイド、インストールはClaude Codeの環境構築方法、VS Codeでの使い方はClaude CodeをVS Codeで使う方法にまとめています。Claude Code自体の概要はClaude Codeとは？をご覧ください。

MCPやClaude Codeを使ったアプリ開発を体系的に学びたい人向けに、テックジムには生成AI（ChatGPT・Claude・Claude Code・Codex・Cursor・Gemini）やAIエージェントを使ってアプリ開発や業務効率化を学ぶAI駆動開発コースもあります。

よくある質問

Q. Claude CodeでMCPサーバーを追加するコマンドは？

リモートのサーバーはclaude mcp add --transport http 名前 URL、手元で動かすサーバーはclaude mcp add 名前 -- 起動コマンドです。JSONで設定がある場合はclaude mcp add-json 名前 'JSON'も使えます。

Q. Claude CodeのMCP設定ファイルはどこにありますか？

localとuserスコープはホームディレクトリの~/.claude.json、projectスコープはプロジェクト直下の.mcp.jsonに保存されます。チームで共有したいときは--scope projectで追加して.mcp.jsonをコミットします。

Q. すべてのプロジェクトで同じMCPサーバーを使うには？

--scope userを付けて追加します。例：claude mcp add --transport http hubspot --scope user URL。既定のlocalスコープだと、追加したプロジェクトでしか使えません。

Q. MCPサーバーを削除・一時停止するには？

削除はclaude mcp remove 名前です。設定を残したまま止めたいときは、Claude Codeの中で/mcpを開いてそのサーバーをオフにします。

Q. MCPサーバーにつながらないときは？

claude mcp get 名前で状態を確認し、認証が必要なら/mcpかclaude mcp login 名前でログインします。stdioのサーバーは、--より後ろの起動コマンドをターミナルで単独で動かして、エラーが出ないか確かめます。

無料のClaude Code講座のご案内

テックジム東京本校では、Claude Codeの体験講座を毎週土曜15時から無料で開いています。ノートPCを持参し、対面のハンズオンで1時間、未経験の方でも参加できます（中学生以上）。詳しくはゼロから始めるClaude Code講座【東京本校・リアル開催】をご覧ください。

対面・無料｜東京・永田町で毎週土曜日13時

1回の参加で、プログラミングの構造がわかる

ゼロからはじめるPython入門講座

8年間・累計600回開催／これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する｜開催日程を見る

参加費は無料です

プログラミング学習に関するお役立ちコンテンツ

カテゴリー: コラム