Gemini Researcher

A lightweight, stateless MCP (Model Context Protocol) server that lets developer agents (Claude Code, GitHub Copilot) delegate deep repository analysis to the Gemini CLI. The server is read-only, returns structured JSON (as text content), and is optimized to reduce the calling agent's context and model usage.

Status: v1 complete. Core features are stable, but still early days. Feedback welcome!

If this project extended the lifespan of your usage window, ⭐ please consider giving it a star! :)

Primary goals:

• Reduce agent context usage by letting Gemini CLI read large codebases locally and do its own research
• Reduce calling-agent model usage by offloading heavy analysis to Gemini
• Keep the server stateless and read-only for safety

Why use this?

Instead of copying entire files into your agent's context (burning tokens and cluttering the conversation), this server lets Gemini CLI read files directly from your project. Your agent sends a research query, Gemini does the heavy lifting with its large context window, and returns structured results. You save tokens, your agent stays focused, and complex codebase analysis becomes practical.

Verified clients: Claude Code, Cursor, VS Code (GitHub Copilot)

[!NOTE] It definitely works with other clients, but I haven't personally tested them yet. Please open an issue if you try it elsewhere!

Table of contents

• Gemini Researcher
  • Overview
  • Prerequisites
  • Quickstart
    • Step 1: Validate environment
    • Step 2: Configure your MCP client
    • Step 3: Restart your MCP client
    • Step 4: Test it
  • Tools
    • Example workflows
  • Docker
  • Troubleshooting (common issues)
  • Contributing
  • License

Overview

Gemini Researcher accepts research-style queries over the MCP protocol and spawns the Gemini CLI in headless mode to perform large-context analysis on local files referenced with @path. Results are returned as pretty-printed JSON strings suitable for programmatic consumption by agent clients.

Runtime safety contract

Canonical runtime semantics are maintained in docs/runtime-contract.md. This section is a quick summary for end users.

Gemini Researcher enforces this invocation contract for analysis requests:

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

• The server uses -p/--prompt for explicit non-interactive headless execution.
• The server does not use -y/--yolo in server-generated argv.
• Read-only behavior is enforced via bundled admin policy by default.
• Admin-policy strict enforcement can be relaxed with GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 (or false|no|off).

Read-only policy behavior

• Default mode is strict fail-closed enforcement.
• The bundled policy denies known mutating tools (for example: write_file, replace, run_shell_command).
• The policy is deny-list based. If Gemini introduces new mutating tool names in future releases, policy updates may be required.
• Extensions remain enabled by design. This is convenient, but means policy

... View full README on GitHub