Gemini Researcher

🚀 Gemini Researcher

Gemini Researcher 是一个轻量级、无状态的 MCP（模型上下文协议）服务器，它允许开发者代理（如 Claude Code、GitHub Copilot）将深度代码库分析任务委托给 Gemini CLI。该服务器为只读模式，返回结构化的 JSON 数据（以文本形式呈现），旨在减少调用代理的上下文和模型使用量。

项目状态

当前版本为 v1，核心功能已稳定，但仍处于早期阶段，欢迎反馈！

项目目标

• 让 Gemini CLI 在本地读取大型代码库并进行自主研究，减少代理上下文的使用。
• 将繁重的分析任务卸载到 Gemini，减少调用代理的模型使用量。
• 为确保安全，服务器采用无状态和只读模式。

为何使用本项目

通常，将整个文件复制到代理的上下文中会消耗大量令牌并使对话变得混乱。而使用本服务器，Gemini CLI 可以直接从项目中读取文件。代理发送研究查询，Gemini 利用其大上下文窗口进行繁重的分析，并返回结构化结果。这样既能节省令牌，又能使代理保持专注，让复杂的代码库分析变得更加可行。

已验证的客户端

Claude Code、Cursor、VS Code（GitHub Copilot）

⚠️ 重要提示

该项目肯定也适用于其他客户端，但尚未进行个人测试。如果您在其他客户端上使用，请提交一个 issue！

🚀 快速开始

步骤 1：验证环境

运行设置向导，验证 Gemini CLI 是否已安装并完成身份验证：

npx gemini-researcher init

步骤 2：配置 MCP 客户端

标准配置

适用于大多数工具：

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

VS Code 配置

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

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

Claude Code 配置

选项 1：命令行（推荐）

• 本地（用户范围）

# 通过 CLI 添加 MCP 服务器
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# 验证是否添加成功
claude mcp list

• 项目范围 导航到项目目录，然后运行：

# 通过 CLI 添加 MCP 服务器
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# 验证是否添加成功
claude mcp list

选项 2：手动配置

添加到项目根目录的 .mcp.json 中（项目范围）：

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

或者添加到 ~/.claude/settings.json 中（本地范围）。

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

Cursor 配置

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

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

⚠️ 重要提示

服务器会自动将 IDE 打开工作区的目录或终端所在目录作为项目根目录。若要分析其他目录，可选择设置 PROJECT_ROOT：

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

步骤 3：重启 MCP 客户端

步骤 4：测试

向代理提问："Use gemini-researcher to analyze the project."

✨ 主要特性

• 接受基于 MCP 协议的研究式查询。
• 以无头、只读模式启动 Gemini CLI，对 @path 引用的本地文件进行大上下文分析。
• 返回格式化的 JSON 字符串，便于代理客户端进行编程式消费。

📦 安装指南

前提条件

• 安装 Node.js 18 及以上版本。
• 安装 Gemini CLI：npm install -g @google/gemini-cli。
• 对 Gemini CLI 进行身份验证（推荐：gemini → 使用 Google 登录）或设置 GEMINI_API_KEY。

快速检查

node --version
gemini --version

💻 使用示例

基础用法

# 验证环境
npx gemini-researcher init

高级用法

理解安全漏洞

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 Hub 上获取预构建的多平台 Docker 镜像：

# 拉取镜像（适用于 Intel/AMD 和 Apple Silicon）
docker pull capybearista/gemini-researcher:latest

# 运行服务器（挂载项目并提供 API 密钥）
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

MCP 客户端 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"
      }
    }
  }
}

⚠️ 重要提示

• -i 标志是 stdio 传输所必需的。
• 容器将项目挂载到 /workspace（项目根目录）。
• 将 /path/to/your/project 替换为实际的项目路径。
• 将 your-api-key 替换为实际的 Gemini API 密钥（这是 Docker 使用所必需的）。

常见问题排查

• GEMINI_CLI_NOT_FOUND：安装 Gemini CLI：npm install -g @google/gemini-cli。
• AUTH_MISSING：运行 gemini 并进行身份验证，或设置 GEMINI_API_KEY。
• .gitignore 阻止文件：Gemini 默认遵循 .gitignore；如果您有意包含被忽略的文件，请在 gemini /settings 中切换 fileFiltering.respectGitIgnore（注意：这会全局更改 Gemini 的行为）。
• PATH_NOT_ALLOWED：所有 @path 引用必须在配置的项目根目录内解析（默认是 process.cwd()）。使用 validate_paths 预检查路径。
• QUOTA_EXCEEDED：服务器会尝试使用备用模型；如果所有层级都已用尽，请缩小范围（使用 quick_query）或等待配额重置。

📄 许可证

本项目采用 BSD-3-Clause 许可证。

为 AI 辅助开发社区用心打造 ❤️