Gemini Researcher

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

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

トークンの節約になった場合は、 ⭐ ぜひスターをお願いします！ :)

主な目的:

• Gemini CLIがローカルで大規模なコードベースを読み取り、独自にリサーチを行うことで、エージェントのコンテキスト使用量を削減する

• 重い分析をGeminiにオフロードすることで、呼び出し元エージェントのモデル使用量を削減する

• 安全のためにサーバーをステートレスかつ読み取り専用に保つ

なぜこれを使うのか？

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

検証済みクライアント: Claude Code、Cursor、VS Code (GitHub Copilot)

目次

• Gemini Researcher

  • 概要

  • 前提条件

  • クイックスタート

    • ステップ1: 環境の検証

    • ステップ2: MCPクライアントの設定

    • ステップ3: MCPクライアントの再起動

    • ステップ4: テスト

  • ツール

    • ワークフローの例

  • Docker

  • トラブルシューティング（一般的な問題）

  • 貢献

  • ライセンス

概要

Gemini Researcherは、MCPプロトコルを介してリサーチ形式のクエリを受け取り、ヘッドレスモードでGemini CLIを起動して、@pathで参照されるローカルファイルを分析します。結果は、エージェントクライアント向けにフォーマットされたJSON文字列として返されます。

ランタイム安全契約

標準的なランタイムセマンティクスは docs/runtime-contract.md に維持されています。

Gemini Researcherは、分析リクエストに対して以下の呼び出し契約を強制します：

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

• サーバーは、明示的な非対話型ヘッドレス実行のために -p/--prompt を使用します。

• サーバーは、サーバー生成のargvで -y/--yolo を使用しません。

• 読み取り専用動作は、デフォルトでバンドルされた管理ポリシーによって強制されます。

• 管理ポリシーの厳格な強制は、GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0（または false|no|off）で緩和できます。

読み取り専用ポリシーの動作

• デフォルトモードは、厳格なフェイルクローズ強制です。

• バンドルされたポリシーは、既知の変更ツール（例: write_file、replace、run_shell_command）を拒否します。

• ポリシーは拒否リストに基づいています。Geminiが将来のリリースで新しい変更ツール名を導入した場合、ポリシーの更新が必要になる可能性があります。

• 拡張機能は設計上有効なままです。これは便利ですが、本番環境ではポリシーの強制を有効にしておくべきであることを意味します。

認証とヘルスチェックのセマンティクス

includeDiagnostics: true を指定して health_check を実行すると、診断情報には認証状態と強制ステータスが含まれます。

health_check.status は以下の通りです：

• ok: Geminiが利用可能で、認証が設定されており、厳格な読み取り専用強制が満たされている（または環境変数で意図的に緩和されている）場合のみ。

• 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"
      ]
    }
  }
}

VS CodeのMCP設定に追加します（必要に応じて .vscode/mcp.json を作成してください）：

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

オプション1: コマンドライン（推奨）

ローカル（ユーザー全体）スコープ

# 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

オプション2: 手動設定

プロジェクトルートの .mcp.json に追加します（プロジェクトスコープ）：

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

または、ローカルスコープ用に ~/.claude/settings.json に追加します。

サーバーを追加した後、Claude Codeを再起動し、/mcp を使用して接続を確認します。

Cursor Settings -> Tools & MCP -> Add a Custom MCP Server に移動します。以下の設定を追加します：

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

例

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

ステップ3: MCPクライアントの再起動

ステップ4: テスト

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

ツール

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

ワークフローの例

セキュリティ脆弱性の理解:

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

quick_query

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

deep_research

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

analyze_directory

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

validate_paths

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

health_check

{
  "includeDiagnostics": true
}

fetch_chunk

{
  "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"
      }
    }
  }
}

トラブルシューティング（一般的な問題）

• GEMINI_CLI_NOT_FOUND: Gemini CLIをインストールしてください: npm install -g @google/gemini-cli

• 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 が含まれている必要があります）。

• 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 License