Gemini Researcher MCP server

Gemini Researcher

A lightweight, stateless MCP (Model Context Protocol) server that lets developer agents (Claude Code, GitHub Copilot) hand off deep repository analysis to the Gemini CLI. The server is read-only, returns structured JSON (as text content), and is designed 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 saved you tokens, ⭐ please consider giving it a star! :)

The 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 reads and synthesizes using 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
• Platform guides

Overview

Gemini Researcher accepts queries from your AI agent and uses Gemini CLI to analyze your local code files. Results are returned as formatted JSON for your agent to use.

Runtime safety

The server runs Gemini CLI with safety restrictions enabled. See docs/runtime-contract.md for full technical details.

Default invocation pattern:

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

Key safety points:

• Uses --approval-mode default (not yolo mode) for controlled execution
• Enforces read-only policy by default to prevent file changes
• Policy blocks mutating tools like writefile, replace, runshell_command
• Strict enforcement can be disabled with GEMINIRESEARCHERENFORCEADMINPOLICY=0 (not recommended)

Auth and health check

Run health_check with includeDiagnostics: true to see auth status and server health.

Shortened. The full README is on GitHub.