Gemini CLI に MCP サーバーを追加する:settings.json の mcpServers の書き方と接続確認

Gemini CLI も MCP(Model Context Protocol)に対応しており、ブラウザ操作やドキュメント検索などの外部ツールを接続できます。設定は settings.json の mcpServers に書く JSON 形式で、Claude Code の .mcp.json とほぼ同じ構造です。

この記事では、設定ファイルの場所と書き方、接続確認、ツールの許可設定、動かないときの切り分けをまとめます。

設定ファイルの場所

スコープ	パス	用途
ユーザー	~/.gemini/settings.json	自分の全プロジェクトで使うサーバー
プロジェクト	<リポジトリ>/.gemini/settings.json	チームで共有するサーバー(Git 管理)

両方に設定がある場合は結合され、同名のサーバーはプロジェクト側が優先されます。

mcpServers の書き方

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 30000
    }
  }
}

キー	意味
command	サーバーを起動するコマンド
args	引数の配列
env	サーバーに渡す環境変数。$VAR や ${VAR} でシェルの環境変数を参照できる
cwd	起動時の作業ディレクトリ(任意)
timeout	応答待ちのミリ秒(任意)
url / httpUrl	リモートサーバーに接続する場合の URL(stdio の代わりに指定)

接続を確認する

Gemini CLI を起動し、/mcp を実行します。サーバーごとに「接続済み」「接続中」「切断」の状態と、提供されるツール名の一覧が表示されます。/tools では、組み込みツールと MCP ツールを合わせた一覧が見られます。

初回起動時は、サーバーが提供するツールを Gemini に使わせてよいか確認が出る場合があります。

ツール実行の許可

MCP のツールも、実行前に確認が入ります。毎回確認したくないツールは、確認ダイアログで「常に許可」を選ぶか、settings.json で信頼するサーバーを指定します。

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "trust": true
    }
  }
}

trust を true にすると、そのサーバーのツールは確認なしで実行されます。読み取り専用のサーバー(ドキュメント検索など)に限って使い、書き込みや外部送信を行うサーバーには付けないでください。設定キーの対応状況はバージョンで変わるため、公式の設定リファレンスで確認してください。

使い方の例

• Playwright: 「開発サーバーを起動して、トップページのスクリーンショットを撮って、レイアウト崩れがないか確認して」
• Context7: 「Next.js の最新の App Router のドキュメントを参照して、動的ルートの書き方を確認してから実装して」
• GitHub: 「Issue #12 の内容を読んで、修正方針を提案して」

動かないときの切り分け

1. サーバーを単体で起動する: npx @playwright/mcp@latest をターミナルで直接実行し、エラーが出ないか確認します。
2. 環境変数: echo $GITHUB_TOKEN で値があるか確認します。Gemini CLI を起動したシェルに環境変数がなければ渡りません。
3. JSON の構文: 末尾のカンマ、クォートの閉じ忘れが多い原因です。gemini 起動時に設定ファイルのエラーが表示されます。
4. タイムアウト: 初回の npx はパッケージのダウンロードに時間がかかります。timeout を長めにするか、事前に一度手動で起動しておきます。
5. Node.js のバージョン: MCP サーバー側が要求するバージョンを満たしているか確認します。

Claude Code・Codex との違い

ツール	設定ファイル	形式
Gemini CLI	~/.gemini/settings.json / .gemini/settings.json	JSON の mcpServers
Claude Code	.mcp.json / ~/.claude.json	JSON の mcpServers
Codex	~/.codex/config.toml	TOML の [mcp_servers.名前]

Claude Code とはキー名まで同じなので、.mcp.json の内容を .gemini/settings.json に貼るだけで動くことが多いです。Claude Code の手順は Claude Code に MCP サーバーを追加する方法、Codex は Codex CLI に MCP サーバーを設定する を参照してください。最初に入れるサーバーの候補は コーディング AI で最初に入れるべき MCP サーバー にまとめています。

まとめ

• ~/.gemini/settings.json(ユーザー)または .gemini/settings.json(プロジェクト)の mcpServers に書く
• command / args / env は Claude Code の .mcp.json と同じ構造。トークンは環境変数から読ませる
• /mcp で接続状態、/tools でツール一覧を確認する
• trust は読み取り専用のサーバーに限定し、書き込み系は確認を残す