Gemini Researcher

一个轻量级、无状态的 MCP（模型上下文协议）服务器，允许开发人员代理（Claude Code、GitHub Copilot）将深度存储库分析任务移交给 Gemini CLI。该服务器为只读模式，返回结构化 JSON（作为文本内容），旨在减少调用代理的上下文和模型使用量。

状态：v1 已完成。核心功能稳定，但仍处于早期阶段。欢迎反馈！

如果这为您节省了 Token， ⭐ 请考虑给它点个星标！:)

主要目标：

• 通过让 Gemini CLI 在本地读取大型代码库并自行进行研究，减少代理的上下文使用量

• 通过将繁重的分析任务卸载给 Gemini，减少调用代理的模型使用量

• 保持服务器无状态且只读，以确保安全

为什么要使用它？

与其将整个文件复制到代理的上下文中（消耗 Token 并使对话混乱），此服务器允许 Gemini CLI 直接从您的项目中读取文件。您的代理发送研究查询，Gemini 使用其大上下文窗口进行读取和综合，并返回结构化结果。您可以节省 Token，代理保持专注，复杂的代码库分析也变得切实可行。

已验证的客户端： Claude Code, Cursor, VS Code (GitHub Copilot)

目录

• Gemini Researcher

  • 概述

  • 先决条件

  • 快速入门

    • 第 1 步：验证环境

    • 第 2 步：配置您的 MCP 客户端

    • 第 3 步：重启您的 MCP 客户端

    • 第 4 步：测试它

  • 工具

    • 示例工作流

  • Docker

  • 故障排除（常见问题）

  • 贡献

  • 许可证

概述

Gemini Researcher 通过 MCP 协议接收研究风格的查询，并以无头模式启动 Gemini CLI，以分析使用 @path 引用的本地文件。结果以格式化的 JSON 字符串形式返回给代理客户端。

运行时安全契约

规范的运行时语义维护在 docs/runtime-contract.md 中。

Gemini Researcher 对分析请求强制执行此调用契约：

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

• 服务器使用 -p/--prompt 进行显式的非交互式无头执行。

• 服务器在服务器生成的 argv 中不使用 -y/--yolo。

• 默认通过捆绑的管理策略强制执行只读行为。

• 可以通过 GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0（或 false|no|off）放宽管理策略的严格执行。

只读策略行为

• 默认模式是严格的故障关闭（fail-closed）执行。

• 捆绑的策略拒绝已知的变异工具（例如：write_file, replace, run_shell_command）。

• 该策略基于拒绝列表。如果 Gemini 在未来版本中引入新的变异工具名称，可能需要更新策略。

• 扩展程序按设计保持启用状态。这很方便，但意味着在生产环境中应保持策略执行处于启用状态。

身份验证和健康语义

当您使用 includeDiagnostics: true 运行 health_check 时，诊断信息包括身份验证状态和执行状态。

health_check.status 为：

• ok：仅当 Gemini 可用、身份验证已配置且满足严格的只读执行（或通过环境变量切换有意放宽）时。

• degraded：适用于所有设置/安全/身份验证不确定的路径。

先决条件

• 已安装 Node.js 18+

• 已安装 Gemini CLI：npm install -g @google/gemini-cli

• Gemini CLI 已通过身份验证（推荐：gemini → 使用 Google 登录）或设置了 GEMINI_API_KEY

快速检查：

node --version
gemini --version

快速入门

第 1 步：验证环境

运行设置向导以验证 Gemini CLI 是否已安装并经过身份验证：

npx gemini-researcher init

第 2 步：配置您的 MCP 客户端

标准配置适用于大多数工具：

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

添加到您的 VS Code MCP 设置中（如果需要，请创建 .vscode/mcp.json）：

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

选项 1：命令行（推荐）

本地（用户范围）作用域

# 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

选项 2：手动配置

添加到项目根目录下的 .mcp.json 中（项目作用域）：

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

或者添加到 ~/.claude/settings.json 中以获取本地作用域。

添加服务器后，重启 Claude Code 并使用 /mcp 验证连接。

转到 Cursor Settings -> Tools & MCP -> Add a Custom MCP Server。添加以下配置：

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

示例

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

第 3 步：重启您的 MCP 客户端

第 4 步：测试它

询问您的代理：“使用 gemini-researcher 分析该项目。”

工具

所有工具都返回结构化 JSON（作为 MCP 文本内容）。大型响应会被分块（每个块约 10KB）并缓存 1 小时。

示例工作流

了解安全漏洞：

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

快速代码解释：

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

映射不熟悉的代码库：

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

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

预构建的多平台 Docker 镜像可在 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

用于 Docker 的 MCP 客户端配置：

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

故障排除（常见问题）

• GEMINI_CLI_NOT_FOUND：安装 Gemini CLI：npm install -g @google/gemini-cli

• AUTH_MISSING：运行 gemini 并进行身份验证，或设置 GEMINI_API_KEY

• AUTH_UNKNOWN：无法确认身份验证（通常是网络/CLI 探测失败）。验证 gemini 是否可以交互式工作，然后重试。

• ADMIN_POLICY_MISSING：重新安装包或验证已安装包中是否存在 policies/read-only-enforcement.toml。

• ADMIN_POLICY_UNSUPPORTED：将 Gemini CLI 升级到 v0.36.0+（gemini --help 应包含 --admin-policy）。

• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0：禁用严格的启动硬故障策略执行。这会削弱故障关闭保证。

• .gitignore 阻止文件：Gemini 默认遵循 .gitignore；如果您有意包含被忽略的文件，请在 gemini /settings 中切换 fileFiltering.respectGitIgnore（注意：这会全局更改 Gemini 的行为）

• PATH_NOT_ALLOWED：所有 @path 引用必须在配置的项目根目录（默认为 process.cwd()）内解析。使用 validate_paths 预检查路径。

• QUOTA_EXCEEDED：服务器会使用回退模型重试；如果所有层级都已耗尽，请缩小范围（使用 quick_query）或等待配额重置。

贡献

阅读 贡献指南 以开始。

快速链接：

• 开发设置

• 运行测试

• 代码准则

• 提交更改

许可证

BSD-3-Clause 许可证