Claude CodeでMCPサーバーを設定する具体的な手順を徹底解説。claude mcp addコマンド、settings.json、スコープの使い分け、トラブルシューティングまで網羅します。
使い方ガイド
公開: by ToolCraft Lab 約9分で読めます

Claude Code MCP設定 完全ガイド — サーバーの追加からトラブルシューティングまで【2026年版】

Claude CodeでMCPサーバーを設定する具体的な手順を徹底解説。claude mcp addコマンド、settings.json、スコープの使い分け、トラブルシューティングまで網羅します。

#Claude Code#MCP#設定

Claude CodeでMCPサーバーを設定する

Claude Codeの真の力を引き出すには、MCPサーバーの設定が不可欠です。しかし「コマンドの使い方がわからない」「設定ファイルの書き方が不明」「サーバーが動かない」という声をよく聞きます。この記事では、Claude CodeにおけるMCP設定のすべてを、ステップバイステップで解説します。

Claude Code は MCP（Model Context Protocol）に対応したホストアプリケーションです。MCPサーバーを追加することで、ファイル操作、データベース接続、Web検索、外部API連携など、Claude Code の能力を大幅に拡張できます。

この記事でわかること

  • claude mcp add コマンドの使い方と全オプション
  • 設定ファイル（.mcp.json、~/.claude.json）の構造
  • スコープ（プロジェクト / ユーザー）の使い分け
  • 環境変数の渡し方
  • よくあるエラーと解決策

前提条件

以下がインストール・設定済みであることを確認してください。

# Node.js 18以上
node -v
# v18.x.x 以上であること

# Claude Code
claude --version
# 最新版であること

# Claude Pro または Max プランに加入済みであること

MCPサーバーの多くは npx 経由で実行するため、npm（Node.jsに同梱）が使える状態であれば問題ありません。

基本: claude mcp add コマンド

MCPサーバーの追加は claude mcp add コマンドで行います。

コマンドの基本構文

claude mcp add <サーバー名> [オプション] -- <コマンド> [引数...]

-- の後ろに、MCPサーバーの起動コマンドとその引数を指定します。

最もシンプルな例

# ファイルシステムサーバーを追加
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src

このコマンドは以下を行います。

  1. filesystem という名前でMCPサーバーを登録
  2. 起動コマンドとして npx -y @modelcontextprotocol/server-filesystem ./src を設定
  3. プロジェクトスコープ（デフォルト）に保存

主要オプション一覧

オプション説明例
-s, --scope設定スコープ（project / user）-s user
-e, --env環境変数を指定（KEY=VALUE）-e API_KEY=xxx
-t, --transport通信方式（stdio / sse）-t sse

スコープの使い分け

MCPサーバーの設定は2つのスコープに保存できます。それぞれの用途と保存場所を理解しておきましょう。

プロジェクトスコープ（デフォルト）

特定のプロジェクトでのみ使うサーバーを設定します。設定はプロジェクトルートの .mcp.json に保存されます。

# プロジェクトスコープ（デフォルト、-s project と同じ）
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost:5432/myapp_dev

保存先: <プロジェクトルート>/.mcp.json

メリット:

  • プロジェクトに特化したサーバー設定をGitで管理できる
  • チームメンバーと設定を共有できる
  • プロジェクトを離れると自動的に無効になる

ユーザースコープ

すべてのプロジェクトで共通して使いたいサーバーを設定します。

# ユーザースコープ
claude mcp add -s user memory -- npx -y @modelcontextprotocol/server-memory
claude mcp add -s user brave-search -- npx -y @modelcontextprotocol/server-brave-search

保存先: ~/.claude.json

メリット:

  • どのプロジェクトでも自動的に利用可能
  • Web検索やメモリなど、汎用的なサーバーに最適
  • 一度設定すれば全プロジェクトに反映

おすすめの使い分け

サーバー種別スコープ理由
Filesystemprojectプロジェクトごとに許可ディレクトリが異なる
PostgreSQL / SQLiteprojectDB接続先はプロジェクト固有
GitHubuserどのプロジェクトでも使う
Brave Searchuser汎用的な検索
Memoryuserセッション横断で記憶を保持
FetchuserどのプロジェクトでもURL取得に使う

環境変数の設定方法

MCPサーバーにはAPIキーやトークンが必要なものがあります。環境変数を渡す方法は3つあります。

方法1: -e オプションで直接指定

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx -- npx -y @modelcontextprotocol/server-github

設定ファイルには以下のように保存されます。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

注意: -e で設定した値は設定ファイルに平文で保存されます。.mcp.json をGitにコミットする場合は、トークンの値を空にしてシェルの環境変数から読み込む方式を使ってください。

方法2: シェルの環境変数を利用

# .zshrc や .bashrc に追加
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
export BRAVE_API_KEY=your_brave_api_key

# サーバー追加時に -e を省略
claude mcp add github -- npx -y @modelcontextprotocol/server-github

MCPサーバーのプロセスはシェルの環境変数を継承するため、この方法が最も安全です。

方法3: 設定ファイルを直接編集

.mcp.json や ~/.claude.json を直接編集する方法です。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    }
  }
}

env の値を空にしておき、シェルの環境変数から実際の値を読み込ませるパターンがチーム開発ではおすすめです。

設定ファイルの構造

.mcp.json（プロジェクトスコープ）

{
  "mcpServers": {
    "サーバー名": {
      "command": "起動コマンド",
      "args": ["引数1", "引数2"],
      "env": {
        "ENV_KEY": "value"
      }
    }
  }
}

フルの設定例

実際のプロジェクトで使う設定例を示します。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./tests"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://dev:dev@localhost:5432/myapp_dev"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

MCPサーバーの管理コマンド

サーバー一覧の確認

# 登録済みサーバーの一覧を表示
claude mcp list

出力例:

Project scope (.mcp.json):
  filesystem: npx -y @modelcontextprotocol/server-filesystem ./src
  postgres: npx -y @modelcontextprotocol/server-postgres postgresql://...

User scope (~/.claude.json):
  memory: npx -y @modelcontextprotocol/server-memory
  brave-search: npx -y @modelcontextprotocol/server-brave-search

サーバーの削除

# プロジェクトスコープから削除
claude mcp remove filesystem

# ユーザースコープから削除
claude mcp remove -s user memory

サーバーの詳細確認

# 特定サーバーの設定内容を表示
claude mcp get filesystem

リモートMCPサーバーの接続（SSE通信）

ローカルで起動するサーバー（stdio）だけでなく、リモートで稼働しているMCPサーバーにもHTTP経由で接続できます。

# SSE（Server-Sent Events）通信でリモートサーバーに接続
claude mcp add remote-api -t sse -- https://mcp.example.com/sse

リモートMCPサーバーは以下のようなケースで使います。

  • チーム共有のMCPサーバー（共通のDBアクセスなど）
  • SaaS提供のMCPエンドポイント
  • 社内ネットワーク上のサーバー

認証付きリモートサーバー

claude mcp add remote-api -t sse -e API_KEY=your_key -- https://mcp.example.com/sse

Claude Code 内でのMCP活用

MCPサーバーを設定したら、Claude Code 内で自然言語で指示するだけで使えます。

ファイル操作の例

> srcディレクトリ内のTypeScriptファイルをすべてリストアップして

DB操作の例

> usersテーブルのスキーマを確認して、最新10件のレコードを表示して

複合的な操作の例

> GitHubのIssue #42を読んで、関連するコードを修正して、テストを実行して

Claude Code は利用可能なMCPツールを把握しており、指示内容に応じて適切なツールを自動で選択します。初回はツール実行の承認を求められるので、内容を確認して許可してください。

ツール実行の自動承認

毎回承認を求められるのが手間な場合は、--allowedTools オプションで特定のツールを自動承認できます。

# 特定のMCPツールを自動承認
claude --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

ツール名は mcp__<サーバー名>__<ツール名> の形式です。

トラブルシューティング

「MCPサーバーが見つからない」エラー

原因: 設定ファイルのパスやサーバー名が間違っている。

# 設定を確認
claude mcp list

# 再追加
claude mcp remove filesystem
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src

「サーバーの起動に失敗」エラー

原因: npx のキャッシュが古い、またはNode.jsのバージョンが古い。

# npxのキャッシュをクリア
npx clear-npx-cache

# もしくはグローバルにインストール
npm install -g @modelcontextprotocol/server-filesystem

# パスを指定して追加
claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem ./src

「環境変数が設定されていない」エラー

原因: APIキーやトークンが環境変数に設定されていない。

# 環境変数が設定されているか確認
echo $GITHUB_PERSONAL_ACCESS_TOKEN

# 設定されていなければ追加（.zshrc の場合）
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx' >> ~/.zshrc
source ~/.zshrc

サーバーが応答しない

原因: サーバープロセスがハングしている。

# サーバーをリセット
claude mcp reset

# Claude Codeを再起動
claude

ツールが一覧に表示されない

原因: サーバーは起動しているが、ツールの登録が正しく行われていない。

# サーバーを再追加（最新版を指定）
claude mcp remove <name>
claude mcp add <name> -- npx -y <package>@latest <args>

実践的な設定パターン

パターン1: 個人開発者の最小構成

# ユーザースコープ（全プロジェクト共通）
claude mcp add -s user fetch -- npx -y @modelcontextprotocol/server-fetch
claude mcp add -s user memory -- npx -y @modelcontextprotocol/server-memory

# プロジェクトスコープ
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src

パターン2: フルスタック開発

# ユーザースコープ
claude mcp add -s user github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github
claude mcp add -s user brave-search -e BRAVE_API_KEY=xxx -- npx -y @modelcontextprotocol/server-brave-search
claude mcp add -s user fetch -- npx -y @modelcontextprotocol/server-fetch
claude mcp add -s user memory -- npx -y @modelcontextprotocol/server-memory

# プロジェクトスコープ
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src ./tests
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://dev:dev@localhost:5432/myapp

MCPサーバーの設定パターンをさらに深掘りしたい方は、「MCP実践活用ガイド」で具体的なユースケース別の活用法を紹介しています。

パターン3: チーム共有設定（.mcp.json）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./tests", "./docs"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": ""
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

チームメンバーは DATABASE_URL を自分の環境変数に設定するだけでOKです。

まとめ

Claude CodeのMCP設定は、以下のポイントを押さえればスムーズに行えます。

  • claude mcp add コマンド で簡単にサーバーを追加できる
  • スコープ はプロジェクト固有のものと、全プロジェクト共通のものを使い分ける
  • 環境変数 はシェルの環境変数で管理するのが最も安全
  • .mcp.json でチームと設定を共有できる
  • トラブル時 は claude mcp list と claude mcp reset で状況を確認する

MCPを正しく設定すれば、Claude Code は単なるチャットAIから、外部ツールを自在に操る強力なAIエージェントへと進化します。

関連リンク

関連記事

使い方ガイド

コーディング用プロンプトの書き方10パターン — AI を最大限に活かすプロンプトエンジニアリング

使い方ガイド

Claude Code ultrathink 完全ガイド — 拡張思考モードの使い方と効果的な活用法

使い方ガイド

SEOメタタグ完全ガイド — 必須タグ一覧・チェック方法・よくある設定ミスと対処法