gemini-researcher

Gemini Researcher

開発者向けエージェント（Claude Code、GitHub Copilot）が、Gemini CLI に詳細なリポジトリ分析を委任できる、軽量でステートレスな MCP（Model Context Protocol）サーバーです。このサーバーは読み取り専用で、構造化された JSON（テキストコンテンツとして）を返し、呼び出し元のエージェントのコンテキストとモデルの使用量を削減するよう設計されています。

ステータス：v1 完了。コア機能は安定していますが、まだ初期段階です。フィードバックをお待ちしています！

トークンの節約に役立った場合は、 ⭐ ぜひスターを付けてください！ :)

主な目標：

• Gemini CLI が大規模なコードベースをローカルで読み取り、独自に調査できるようにして、エージェントのコンテキスト使用量を削減する
• 負荷の高い分析を Gemini に委任し、呼び出し元エージェントのモデル使用量を削減する
• 安全性のため、サーバーをステートレスかつ読み取り専用に保つ

これを使う理由

ファイル全体をエージェントのコンテキストにコピーする（トークンを消費し、会話を煩雑にする）のではなく、このサーバーを使えば Gemini CLI がプロジェクトからファイルを直接読み取れます。エージェントが調査クエリを送信すると、Gemini は大きなコンテキストウィンドウを使ってファイルを読み取り、情報を統合して、構造化された結果を返します。トークンを節約でき、エージェントは本来の作業に集中できるため、複雑なコードベースの分析が実用的になります。

動作確認済みのクライアント： Claude Code、Cursor、VS Code（GitHub Copilot）

メモ

ほかのクライアントでも確実に動作しますが、まだ個人的にはテストしていません。ほかの環境で試した場合は、Issue を作成してください！

目次

• Gemini Researcher
  • 概要
  • 前提条件
  • クイックスタート
    • ステップ 1：環境を検証する
    • ステップ 2：MCP クライアントを設定する
    • ステップ 3：MCP クライアントを再起動する
    • ステップ 4：テストする
  • ツール
    • ワークフローの例
  • Docker
  • プラットフォーム別ガイド
  • トラブルシューティング（よくある問題）
  • コントリビューション
  • ライセンス

概要

Gemini Researcher は AI エージェントからのクエリを受け取り、Gemini CLI を使ってローカルのコードファイルを分析します。結果は、エージェントが利用できる形式の JSON として返されます。

実行時の安全性

このサーバーは、安全制限を有効にした状態で Gemini CLI を実行します。詳しい技術情報については、docs/runtime-contract.md を参照してください。

デフォルトの呼び出しパターン：

gemini [ -m <model> ] --output-format json --approval-mode default [--admin-policy <path>] -p "<prompt>"

主な安全対策：

• 制御された実行のために --approval-mode default を使用します（yolo モードではありません）
• ファイル変更を防止するため、デフォルトで読み取り専用ポリシーを適用します
• ポリシーにより、write_file、replace、run_shell_command などの変更を伴うツールがブロックされます
• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 で厳格な適用を無効にできます（推奨されません）

認証とヘルスチェック

includeDiagnostics: true を指定して health_check を実行すると、認証ステータスとサーバーの健全性を確認できます。

health_check.status の値：

• ok：Gemini CLI が利用可能で、認証が機能しており、安全ポリシーが適用されています
• degraded：セットアップが未完了、認証状態が不明、または安全ポリシーが無効です

前提条件

• Node.js 18+ がインストールされていること
• Gemini CLI がインストールされていること：npm install -g @google/gemini-cli
• Gemini CLI で認証済みであること（推奨：gemini → Google でログイン）、または GEMINI_API_KEY を設定していること

簡単な確認：

node --version
gemini --version

クイックスタート

ステップ 1：環境を確認する

セットアップウィザードを実行して、Gemini CLI がインストールされ、認証済みであることを確認します：

npx gemini-researcher init

ステップ 2：MCP クライアントを設定する

標準設定は、ほとんどのツールで使用できます：

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

メモ

Windows ネイティブ環境では、一部の MCP ホストがシェルを介さずにプロセスを起動するため、npm コマンドのシム（npx、gemini）を正常に解決できない場合があります。 PowerShell では動作するのに起動エラー（spawn ... ENOENT／GEMINI_CLI_LAUNCH_FAILED）が発生する場合は、すぐに安定して利用するために Docker または WSL を推奨します。 対応策の全容については、docs/platforms/windows.md を参照してください。

{
  "servers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

# Add the MCP server via CLI
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# Verify it was added
claude mcp list

# Add the MCP server via CLI
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# Verify it was added
claude mcp list

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

{
  "mcpServers": {
    "gemini-researcher": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

メモ

サーバーは、IDE でワークスペースを開いたディレクトリ、またはターミナルの現在のディレクトリをプロジェクトルートとして自動的に使用します。別のディレクトリを分析する場合は、必要に応じて PROJECT_ROOT を設定してください：

例

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

ステップ 3：MCP クライアントを再起動する

ステップ 4：テストする

エージェントに「gemini-researcher を使ってプロジェクトを分析してください」と依頼します。

ツール

すべてのツールは、構造化された JSON（MCP テキストコンテンツとして）を返します。大きなレスポンスはチャンク（各約 10KB）に分割され、1 時間キャッシュされます。

クエリツールのフォールバックチェーンは、モデルファミリーに応じて動作します：

• quick_query：flash -> flash_lite -> auto
• deep_research：pro -> flash -> flash_lite -> auto
• analyze_directory：flash -> flash_lite -> auto

API キー認証を使用する場合、フォールバックはクォータ／容量に関するエラーだけでなく、モデルが利用できない／サポートされていないエラーにも対応します。

ワークフローの例

セキュリティ脆弱性の把握：

Agent: Use deep_research to analyze authentication flow across @src/auth and @src/middleware, focusing on security

コードの簡単な解説：

Agent: Use quick_query to explain the login flow in @src/auth.ts, be concise

不慣れなコードベースのマッピング：

Agent: Use analyze_directory on src/ with depth 3 to understand the project structure

{
  "prompt": "Explain @src/auth.ts login flow",
  "focus": "security",
  "responseStyle": "concise"
}

{
  "prompt": "Analyze authentication across @src/auth and @src/middleware",
  "focus": "architecture",
  "citationMode": "paths_only"
}

{
  "path": "src",
  "depth": 3,
  "maxFiles": 200
}

{
  "paths": ["src/auth.ts", "README.md"]
}

{
  "includeDiagnostics": true
}

{
  "cacheKey": "cache_abc123",
  "chunkIndex": 2
}

Docker

ビルド済みのマルチプラットフォーム Docker イメージを Docker Hub で利用できます：

# Pull the image (works on Intel/AMD and Apple Silicon)
docker pull capybearista/gemini-researcher:latest

# Run the server (mount your project and provide API key)
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

Docker を使った MCP クライアントの設定：

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GEMINI_API_KEY",
        "-v", "/path/to/your/project:/workspace",
        "capybearista/gemini-researcher:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

メモ

• stdio トランスポートには -i フラグが必要です
• コンテナはプロジェクトを /workspace（プロジェクトルート）にマウントします
• /path/to/your/project を実際のプロジェクトパスに置き換えてください
• your-api-key を実際の Gemini API キーに置き換えてください（Docker の使用には必須です）

プラットフォームガイド

• Windows のネイティブ起動モデルと問題の解決方法：docs/platforms/windows.md

トラブルシューティング（よくある問題）

• 問題解決の判断ツリー：

• GEMINI_CLI_NOT_FOUND：Gemini CLI をインストールします：npm install -g @google/gemini-cli
• GEMINI_CLI_LAUNCH_FAILED：これは起動パスの問題であり、認証／機能の問題ではありません。Windows では、シェルを介さない起動コンテキストでコマンド shim が失敗することがあります。対話形式で gemini --help と npx --version が動作することを確認してから、ホストの起動モードに厳しい制約がある場合は Docker または WSL を優先してください。
• GEMINI_RESEARCHER_GEMINI_COMMAND：サーバーが使用する Gemini コマンド名／パスを上書きします（ラッパーまたは固定したバイナリの場所を指定する場合）。
• GEMINI_RESEARCHER_GEMINI_ARGS_PREFIX：すべての呼び出しに追加の Gemini 引数を先頭に付加します（例：--config <file>）。
• health_check の診断では、設定された引数プレフィックスの出力に含まれる、トークンに類似した機密値がマスキングされます。
• AUTH_MISSING：gemini を実行して認証するか、GEMINI_API_KEY を設定します
• AUTH_UNKNOWN：認証を確認できませんでした（多くの場合、ネットワーク／CLI のプローブに失敗しています）。起動エラーがある場合は、まず起動パスを修正してください。それ以外の場合は、対話形式で gemini が動作することを確認してから、再試行してください。
• ADMIN_POLICY_MISSING：パッケージを再インストールするか、インストール済みパッケージに policies/read-only-enforcement.toml が存在することを確認します。
• ADMIN_POLICY_UNSUPPORTED：Gemini CLI を v0.36.0 以降にアップグレードします（gemini --help に --admin-policy が含まれている必要があります）。
• 機能に関するエラー（ADMIN_POLICY_UNSUPPORTED、出力形式がサポートされていない）は、gemini --help のプローブが成功した後にのみ判断してください。プローブの起動に失敗した場合は、まず起動パスの問題として扱います。
• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0：起動時の厳格なポリシーチェックを無効にします。これにより安全性の保証が低下します。
• .gitignore によるファイルのブロック：Gemini はデフォルトで .gitignore を尊重します。無視されたファイルを意図的に含める場合は、gemini /settings で fileFiltering.respectGitIgnore を切り替えてください（注：Gemini の動作が全体的に変わります）。
• PATH_NOT_ALLOWED：すべての @path 参照は、設定されたプロジェクトルート（デフォルトでは process.cwd()）内で解決される必要があります。事前にパスを確認するには validate_paths を使用してください。
• QUOTA_EXCEEDED：サーバーはフォールバックモデルで再試行します。すべての選択肢を使い切った場合は、範囲を縮小する（quick_query を使用する）か、クォータがリセットされるまで待ってください。

貢献

はじめに、貢献ガイドをお読みください。

クイックリンク：

• 開発環境のセットアップ
• テストの実行
• コードのガイドライン
• 変更の提出

ライセンス

BSD-3-Clause ライセンス

AI 支援開発コミュニティのために♡を込めて作成