Gemini Researcher

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
• Troubleshooting (common issues)
• Contributing
• License

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 write_file, replace, run_shell_command
• Strict enforcement can be disabled with GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 (not recommended)

Auth and health check

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

health_check.status values:

• ok: Gemini CLI is available, auth is working, and safety policy is enforced
• degraded: Setup incomplete, auth unclear, or safety policy disabled

Prerequisites

• Node.js 18+ installed
• Gemini CLI installed: npm install -g @google/gemini-cli
• Gemini CLI authenticated (recommended: gemini → Login with Google) or set GEMINI_API_KEY

Quick checks:

node --version

gemini --version

Quickstart

Step 1: Validate environment

Run the setup wizard to verify Gemini CLI is installed and authenticated:

npx gemini-researcher init

Step 2: Configure your MCP client

Standard config works in most of the tools:

{

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

[!NOTE]

On native Windows, some MCP hosts use shell-less process spawning and may not resolve npm command shims reliably (npx, gemini).

If startup fails with launch errors (spawn ... ENOENT / GEMINI_CLI_LAUNCH_FAILED despite working in PowerShell), prefer Docker or WSL for immediate reliability.

See the full remediation tree in docs/platforms/windows.md.

VS Code

Add to your VS Code MCP settings (create .vscode/mcp.json if needed):

{

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

Claude Code

Option 1: Command line (recommended)

Local (user-wide) scope

# Add the MCP server via CLI

claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher

Verify it was added

claude mcp list

Project scope

Navigate to your project directory, then run:

# 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

Option 2: Manual configuration

Add to .mcp.json in your project root (project scope):

{

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

Or add to ~/.claude/settings.json for local scope.

After adding the server, restart Claude Code and use /mcp to verify the connection.

Cursor

Go to Cursor Settings -> Tools & MCP -> Add a Custom MCP Server. Add the following configuration:

{

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

[!NOTE]

The server automatically uses the directory where the IDE opened your workspace as the project root or where your terminal is. To analyze a different directory, optionally set PROJECT_ROOT:

Example

{

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

Step 3: Restart your MCP client

Step 4: Test it

Ask your agent: "Use gemini-researcher to analyze the project."

Tools

All tools return structured JSON (as MCP text content). Large responses are chunked (~10KB per chunk) and cached for 1 hour.

Query tool fallback chains are family-aware:

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

When using API-key auth, fallback also handles model-unavailable/unsupported errors (not only quota/capacity errors).

Example workflows

Understanding a security vulnerability:

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

Quick code explanation:

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

Mapping an unfamiliar codebase:

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

Full tool schemas (for reference)

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

A pre-built multi-platform Docker image is available on 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

For MCP client configuration with Docker:

{

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

[!NOTE]

- The -i flag is required for stdio transport

- The container mounts your project to /workspace (the project root)

- Replace /path/to/your/project with your actual project path

- Replace your-api-key with your actual Gemini API key (this is required for Docker usage)

Platform guides

• Native Windows launch model and remediation: docs/platforms/windows.md

Troubleshooting (common issues)

• Remediation decision tree:

• GEMINI_CLI_NOT_FOUND: Install Gemini CLI: npm install -g @google/gemini-cli
• GEMINI_CLI_LAUNCH_FAILED: This is a launch-path issue, not an auth/capability issue. On Windows, command shims can fail in shell-l