io.github.capyBearista/gemini-researcher

Official

by capyBearista · TypeScript

Stateless MCP server that proxies research queries to Gemini CLI, reducing agent context/model usage

Proxy research queries to Gemini CLI to reduce agent context and model usage.

Topics

ai-agentsclaude-codecost-optimizationcursordeep-researchgemini-cligithub-copilotmcpmodel-context-protocoltypescriptcoding

README.md14 KBView on GitHub

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

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:

bash

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.

authStatus	What it means	Impact
`configured`	Gemini CLI is authenticated	Server ready to use
`unauthenticated`	No valid authentication found	Server marked as degraded
`unknown`	Could not verify auth status	Server marked as degraded

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:

bash

node --version
gemini --version

Quickstart

Step 1: Validate environment

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

bash

npx gemini-researcher init

Step 2: Configure your MCP client

Standard config works in most of the tools:

json

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

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

json

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

</details> <details> <summary>Claude Code</summary>

Option 1: Command line (recommended)

Local (user-wide) scope

bash

# 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:

bash

# 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):

json

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

</details> <details> <summary>Cursor</summary>

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

json

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

</details>

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

json

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

Tool	Purpose	When to use
`quick_query`	Fast analysis with flash model	Quick questions about specific files or small code sections
`deep_research`	In-depth analysis with pro model	Complex multi-file analysis, architecture reviews, security audits
`analyze_directory`	Map directory structure	Understanding unfamiliar codebases, generating project overviews
`validate_paths`	Pre-check file paths	Verify files exist before running expensive queries
`health_check`	Diagnostics	Troubleshooting server/Gemini CLI issues
`fetch_chunk`	Get chunked responses	Retrieve remaining parts of large responses

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:

code

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

Quick code explanation:

code

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

Mapping an unfamiliar codebase:

code

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

<details> <summary>Full tool schemas (for reference)</summary>

quick_query

json

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

deep_research

json

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

analyze_directory

json

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

validate_paths

json

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

health_check

json

{
  "includeDiagnostics": true
}

fetch_chunk

json

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

</details>

Docker

A pre-built multi-platform Docker image is available on Docker Hub:

bash

# 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:

json

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

Error / signal	Run this check first	Change this configuration next
`GEMINI_CLI_LAUNCH_FAILED` or `spawn ... ENOENT`	`gemini --help` and `npx --version` in the same terminal profile used by your MCP host	Prefer Docker or WSL config. If staying native, point host command to a stable shim/binary path and restart host.
`health_check` warning: "resolves only through cmd /c fallback"	Run `health_check` with `includeDiagnostics: true` and inspect `diagnostics.resolution`	Update host config to launch the reported `.cmd` shim directly instead of relying on `cmd /c` fallback.
MCP host cannot launch server via `npx`	`npx --version`	Change host server command from `npx gemini-researcher` to installed binary path (or Docker transport).
`ADMIN_POLICY_UNSUPPORTED` / output format unsupported	`gemini --help` and confirm `--admin-policy`, `json`, `stream-json`	Upgrade Gemini CLI to v0.36.0+
`AUTH_MISSING` / `AUTH_UNKNOWN`	`gemini` interactive login and rerun `health_check`	Authenticate Gemini CLI or set `GEMINI_API_KEY`

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-less spawn contexts. Validate gemini --help and npx --version interactively, then prefer Docker or WSL if host launch mode is strict.
GEMINI_RESEARCHER_GEMINI_COMMAND: Override the Gemini command name/path used by the server (for wrappers or pinned binary locations).
GEMINI_RESEARCHER_GEMINI_ARGS_PREFIX: Prefix extra Gemini args for every invocation (for example --config <file>).
health_check diagnostics redact sensitive token-like values in configured args prefix output.
AUTH_MISSING: Run gemini, and authenticate or set GEMINI_API_KEY
AUTH_UNKNOWN: Auth could not be confirmed (often network/CLI probe failure). If launch errors are present, fix launch-path first; otherwise verify gemini works interactively, then retry.
ADMIN_POLICY_MISSING: Reinstall package or verify policies/read-only-enforcement.toml exists in installed package.
ADMIN_POLICY_UNSUPPORTED: Upgrade Gemini CLI to v0.36.0+ (gemini --help should include --admin-policy).
Capability errors (ADMIN_POLICY_UNSUPPORTED, output format unsupported) should be interpreted only after a successful gemini --help probe. If probe launch fails, treat it as launch-path failure first.
GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0: Disables strict startup policy checks. This reduces safety guarantees.
.gitignore blocking files: Gemini respects .gitignore by default; toggle fileFiltering.respectGitIgnore in gemini /settings if you intentionally want ignored files included (note: this changes Gemini behavior globally)
PATH_NOT_ALLOWED: All @path references must resolve inside the configured project root (process.cwd() by default). Use validate_paths to pre-check paths.
QUOTA_EXCEEDED: Server retries with fallback models; if all options are exhausted, reduce scope (use quick_query) or wait for quota reset.

Contributing

Read the Contributing Guide to get started.

Quick links:

License

BSD-3-Clause License

<p align="center"> Made with ♡ for the AI-assisted dev community </p>

Install

Configuration

Environment variables

GEMINI_API_KEYsecret

Gemini API key (optional if you already authenticated Gemini CLI via "gemini" login)

PROJECT_ROOT

Override the project root directory used for path validation (defaults to current working directory)

RESPONSE_CHUNK_SIZE_KB

Chunk size threshold (KB) for large responses (default: 10)

CACHE_TTL_MS

Chunk cache TTL in milliseconds (default: 3600000 / 1 hour)

DEBUG

Enable debug logging (set to "true" or "1")

GOOGLE_APPLICATION_CREDENTIALS

Vertex AI / Google auth: path to a service account JSON credentials file

GOOGLE_CLOUD_PROJECT

Vertex AI / Google auth: GCP project ID (used by some auth configurations)

VERTEX_AI_PROJECT

Vertex AI / Google auth: Vertex AI project identifier (used by some auth configurations)

claude_desktop_config.json

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "-y",
        "gemini-researcher@1.0.2"
      ],
      "env": {
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
        "PROJECT_ROOT": "<YOUR_PROJECT_ROOT>",
        "RESPONSE_CHUNK_SIZE_KB": "<YOUR_RESPONSE_CHUNK_SIZE_KB>",
        "CACHE_TTL_MS": "<YOUR_CACHE_TTL_MS>",
        "DEBUG": "<YOUR_DEBUG>",
        "GOOGLE_APPLICATION_CREDENTIALS": "<YOUR_GOOGLE_APPLICATION_CREDENTIALS>",
        "GOOGLE_CLOUD_PROJECT": "<YOUR_GOOGLE_CLOUD_PROJECT>",
        "VERTEX_AI_PROJECT": "<YOUR_VERTEX_AI_PROJECT>"
      }
    }
  }
}