Gemini Researcher

🚀 Gemini Researcher

A lightweight, stateless MCP server enabling deep repository analysis delegation to the Gemini CLI for developer agents.

This is a lightweight, stateless MCP (Model Context Protocol) server that allows developer agents (such as Claude Code and GitHub Copilot) to delegate in - depth repository analysis to the Gemini CLI. The server is read - only, returns structured JSON (as text content), and is optimized to reduce the context and model usage of the calling agent.

Status: v1 is complete. Core features are stable, but it's still in the early stage. Feedback is welcome!

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

Primary goals:

• Reduce agent context usage by enabling the Gemini CLI to read large codebases locally and conduct independent research.
• Reduce calling - agent model usage by offloading heavy analysis tasks to Gemini.
• Keep the server stateless and read - only for security.

Why use this?

Instead of copying entire files into the agent's context (which wastes tokens and clutters the conversation), this server allows the Gemini CLI to directly read files from your project. Your agent sends a research query, Gemini performs the complex analysis with its large context window, and returns structured results. This saves tokens, keeps your agent focused, and makes complex codebase analysis feasible.

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

⚠️ Important Note

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

🚀 Quick Start

Step 1: Validate environment

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

npx gemini-researcher init

Step 2: Configure your MCP client

Standard config works in most tools:

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

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

# 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

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

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

⚠️ Important 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."

✨ Features

• Accepts research - style queries over the MCP protocol.
• Spawns the Gemini CLI in headless, read - only mode to perform large - context analysis on local files.
• Returns results as pretty - printed JSON strings for programmatic consumption by agent clients.

📦 Installation

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

Quick checks:

node --version
gemini --version

💻 Usage Examples

Basic Usage

Ask your agent to use the quick_query tool to get a quick explanation of the login flow:

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

Advanced Usage

Use the deep_research tool to conduct an in - depth security analysis across multiple directories:

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

📚 Documentation

Tools

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

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

⚠️ Important 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).

Troubleshooting (common issues)

• GEMINI_CLI_NOT_FOUND: Install Gemini CLI: npm install -g @google/gemini-cli
• AUTH_MISSING: Run gemini, and authenticate or set GEMINI_API_KEY
• .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 tiers are exhausted, reduce scope (use quick_query) or wait for quota reset.

🤝 Contributing

We welcome contributions! Please read the Contributing Guide to get started.

Quick links:

• Development setup
• Running tests
• Code guidelines
• Submitting changes

📄 License

BSD - 3 - Clause License

Made with ♡ for the AI - assisted dev community