{
  "markdown": "# Gemini Researcher\n\n[![NPM Version](https://img.shields.io/npm/v/gemini-researcher?logo=npm)](https://www.npmjs.com/package/gemini-researcher)\n[![NPM Downloads](https://img.shields.io/npm/d18m/gemini-researcher?logo=npm)](https://www.npmjs.com/package/gemini-researcher)\n[![License: BSD-3 Claude](https://img.shields.io/badge/License-BSD%203--Clause-white.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n<a href=\"https://glama.ai/mcp/servers/@capyBearista/gemini-researcher\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@capyBearista/gemini-researcher/badge\" />\n</a>\n\nA 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.\n\nStatus: v1 complete. Core features are stable, but still early days. Feedback welcome!\n\n**If this saved you tokens,** ⭐ please consider giving it a star! :)\n\nThe primary goals:\n- Reduce agent context usage by letting Gemini CLI read large codebases locally and do its own research\n- Reduce calling-agent model usage by offloading heavy analysis to Gemini\n- Keep the server stateless and read-only for safety\n\n**Why use this?**\n\nInstead 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.\n\n**Verified clients:** Claude Code, Cursor, VS Code (GitHub Copilot)\n> [!NOTE] \n> It definitely works with other clients, but I haven't personally tested them yet. Please open an issue if you try it elsewhere!\n\n**Table of contents**\n\n- [Gemini Researcher](#gemini-researcher)\n  - [Overview](#overview)\n  - [Prerequisites](#prerequisites)\n  - [Quickstart](#quickstart)\n    - [Step 1: Validate environment](#step-1-validate-environment)\n    - [Step 2: Configure your MCP client](#step-2-configure-your-mcp-client)\n    - [Step 3: Restart your MCP client](#step-3-restart-your-mcp-client)\n    - [Step 4: Test it](#step-4-test-it)\n  - [Tools](#tools)\n    - [Example workflows](#example-workflows)\n  - [Docker](#docker)\n  - [Platform guides](#platform-guides)\n  - [Troubleshooting (common issues)](#troubleshooting-common-issues)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Overview\n\nGemini 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.\n\n### Runtime safety\n\nThe server runs Gemini CLI with safety restrictions enabled. See `docs/runtime-contract.md` for full technical details.\n\nDefault invocation pattern:\n```bash\ngemini [ -m <model> ] --output-format json --approval-mode default [--admin-policy <path>] -p \"<prompt>\"\n```\n\n**Key safety points:**\n- Uses `--approval-mode default` (not yolo mode) for controlled execution\n- Enforces read-only policy by default to prevent file changes\n- Policy blocks mutating tools like `write_file`, `replace`, `run_shell_command`\n- Strict enforcement can be disabled with `GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0` (not recommended)\n\n### Auth and health check\n\nRun `health_check` with `includeDiagnostics: true` to see auth status and server health.\n\n| authStatus | What it means | Impact |\n|---|---|---|\n| `configured` | Gemini CLI is authenticated | Server ready to use |\n| `unauthenticated` | No valid authentication found | Server marked as degraded |\n| `unknown` | Could not verify auth status | Server marked as degraded |\n\n**health_check.status values:**\n- `ok`: Gemini CLI is available, auth is working, and safety policy is enforced\n- `degraded`: Setup incomplete, auth unclear, or safety policy disabled\n\n## Prerequisites\n- Node.js 18+ installed\n- Gemini CLI installed: `npm install -g @google/gemini-cli`\n- Gemini CLI authenticated (recommended: `gemini` → Login with Google) or set `GEMINI_API_KEY`\n\nQuick checks:\n```bash\nnode --version\ngemini --version\n```\n\n## Quickstart\n\n### Step 1: Validate environment\nRun the setup wizard to verify Gemini CLI is installed and authenticated:\n```bash\nnpx gemini-researcher init\n```\n\n### Step 2: Configure your MCP client\n\n**Standard config** works in most of the tools:\n```json\n{\n  \"mcpServers\": {\n    \"gemini-researcher\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"gemini-researcher\"\n      ]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> On native Windows, some MCP hosts use shell-less process spawning and may not resolve npm command shims reliably (`npx`, `gemini`).\n> If startup fails with launch errors (`spawn ... ENOENT` / `GEMINI_CLI_LAUNCH_FAILED` despite working in PowerShell), prefer Docker or WSL for immediate reliability.\n> See the full remediation tree in [`docs/platforms/windows.md`](docs/platforms/windows.md).\n\n<details>\n<summary>VS Code</summary>\n\nAdd to your VS Code MCP settings (create `.vscode/mcp.json` if needed):\n```json\n{\n  \"servers\": {\n    \"gemini-researcher\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"gemini-researcher\"\n      ]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Claude Code</summary>\n\n**Option 1: Command line (recommended)**\n\nLocal (user-wide) scope\n```bash\n# Add the MCP server via CLI\nclaude mcp add --transport stdio gemini-researcher -- npx gemini-researcher \n\n# Verify it was added\nclaude mcp list\n```\n\nProject scope\n\nNavigate to your project directory, then run:\n```bash\n# Add the MCP server via CLI\nclaude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher\n\n# Verify it was added\nclaude mcp list\n```\n\n**Option 2: Manual configuration**\n\nAdd to `.mcp.json` in your project root (project scope):\n```json\n{\n  \"mcpServers\": {\n    \"gemini-researcher\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"gemini-researcher\"\n      ]\n    }\n  }\n}\n```\n\nOr add to `~/.claude/settings.json` for local scope.\n\nAfter adding the server, restart Claude Code and use `/mcp` to verify the connection.\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\nGo to `Cursor Settings` -> `Tools & MCP` -> `Add a Custom MCP Server`. Add the following configuration:\n```json\n{\n  \"mcpServers\": {\n    \"gemini-researcher\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\n        \"gemini-researcher\"\n      ]\n    }\n  }\n}\n```\n\n</details>\n\n> [!NOTE]\n> 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`:\n\nExample\n```json\n{\n  \"mcpServers\": {\n    \"gemini-researcher\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"gemini-researcher\"\n      ],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n### Step 3: Restart your MCP client\n\n### Step 4: Test it\nAsk your agent: \"Use gemini-researcher to analyze the project.\"\n\n## Tools\n\nAll tools return structured JSON (as MCP text content). Large responses are chunked (~10KB per chunk) and cached for 1 hour.\n\n| Tool | Purpose | When to use |\n|------|---------|-------------|\n| `quick_query` | Fast analysis with flash model | Quick questions about specific files or small code sections |\n| `deep_research` | In-depth analysis with pro model | Complex multi-file analysis, architecture reviews, security audits |\n| `analyze_directory` | Map directory structure | Understanding unfamiliar codebases, generating project overviews |\n| `validate_paths` | Pre-check file paths | Verify files exist before running expensive queries |\n| `health_check` | Diagnostics | Troubleshooting server/Gemini CLI issues |\n| `fetch_chunk` | Get chunked responses | Retrieve remaining parts of large responses |\n\nQuery tool fallback chains are family-aware:\n\n- `quick_query`: `flash -> flash_lite -> auto`\n- `deep_research`: `pro -> flash -> flash_lite -> auto`\n- `analyze_directory`: `flash -> flash_lite -> auto`\n\nWhen using API-key auth, fallback also handles model-unavailable/unsupported errors (not only quota/capacity errors).\n\n### Example workflows\n\n**Understanding a security vulnerability:**\n```\nAgent: Use deep_research to analyze authentication flow across @src/auth and @src/middleware, focusing on security\n```\n\n**Quick code explanation:**\n```\nAgent: Use quick_query to explain the login flow in @src/auth.ts, be concise\n```\n\n**Mapping an unfamiliar codebase:**\n```\nAgent: Use analyze_directory on src/ with depth 3 to understand the project structure\n```\n\n<details>\n<summary>Full tool schemas (for reference)</summary>\n\n**quick_query**\n```json\n{\n  \"prompt\": \"Explain @src/auth.ts login flow\",\n  \"focus\": \"security\",\n  \"responseStyle\": \"concise\"\n}\n```\n\n**deep_research**\n```json\n{\n  \"prompt\": \"Analyze authentication across @src/auth and @src/middleware\",\n  \"focus\": \"architecture\",\n  \"citationMode\": \"paths_only\"\n}\n```\n\n**analyze_directory**\n```json\n{\n  \"path\": \"src\",\n  \"depth\": 3,\n  \"maxFiles\": 200\n}\n```\n\n**validate_paths**\n```json\n{\n  \"paths\": [\"src/auth.ts\", \"README.md\"]\n}\n```\n\n**health_check**\n```json\n{\n  \"includeDiagnostics\": true\n}\n```\n\n**fetch_chunk**\n```json\n{\n  \"cacheKey\": \"cache_abc123\",\n  \"chunkIndex\": 2\n}\n```\n\n</details>\n\n## Docker\n\nA pre-built multi-platform Docker image is available on [Docker Hub](https://hub.docker.com/r/capybearista/gemini-researcher):\n\n```bash\n# Pull the image (works on Intel/AMD and Apple Silicon)\ndocker pull capybearista/gemini-researcher:latest\n\n# Run the server (mount your project and provide API key)\ndocker run -i --rm \\\n  -e GEMINI_API_KEY=\"your-api-key\" \\\n  -v /path/to/your/project:/workspace \\\n  capybearista/gemini-researcher:latest\n```\n\nFor MCP client configuration with Docker:\n```json\n{\n  \"mcpServers\": {\n    \"gemini-researcher\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"GEMINI_API_KEY\",\n        \"-v\", \"/path/to/your/project:/workspace\",\n        \"capybearista/gemini-researcher:latest\"\n      ],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n> [!NOTE]\n> - The `-i` flag is required for stdio transport\n> - The container mounts your project to `/workspace` (the project root)\n> - Replace `/path/to/your/project` with your actual project path\n> - Replace `your-api-key` with your actual Gemini API key (this is required for Docker usage)\n\n## Platform guides\n\n- Native Windows launch model and remediation: [`docs/platforms/windows.md`](docs/platforms/windows.md)\n\n## Troubleshooting (common issues)\n- Remediation decision tree:\n\n| Error / signal | Run this check first | Change this configuration next |\n|---|---|---|\n| `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. |\n| `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. |\n| MCP host cannot launch server via `npx` | `npx --version` | Change host server command from `npx gemini-researcher` to installed binary path (or Docker transport). |\n| `ADMIN_POLICY_UNSUPPORTED` / output format unsupported | `gemini --help` and confirm `--admin-policy`, `json`, `stream-json` | Upgrade Gemini CLI to v0.36.0+ |\n| `AUTH_MISSING` / `AUTH_UNKNOWN` | `gemini` interactive login and rerun `health_check` | Authenticate Gemini CLI or set `GEMINI_API_KEY` |\n\n- `GEMINI_CLI_NOT_FOUND`: Install Gemini CLI: `npm install -g @google/gemini-cli`\n- `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.\n- `GEMINI_RESEARCHER_GEMINI_COMMAND`: Override the Gemini command name/path used by the server (for wrappers or pinned binary locations).\n- `GEMINI_RESEARCHER_GEMINI_ARGS_PREFIX`: Prefix extra Gemini args for every invocation (for example `--config <file>`).\n- `health_check` diagnostics redact sensitive token-like values in configured args prefix output.\n- `AUTH_MISSING`: Run `gemini`, and authenticate or set `GEMINI_API_KEY`\n- `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.\n- `ADMIN_POLICY_MISSING`: Reinstall package or verify `policies/read-only-enforcement.toml` exists in installed package.\n- `ADMIN_POLICY_UNSUPPORTED`: Upgrade Gemini CLI to v0.36.0+ (`gemini --help` should include `--admin-policy`).\n- 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.\n- `GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0`: Disables strict startup policy checks. This reduces safety guarantees.\n- `.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)\n- `PATH_NOT_ALLOWED`: All `@path` references must resolve inside the configured project root (`process.cwd()` by default). Use `validate_paths` to pre-check paths.\n- `QUOTA_EXCEEDED`: Server retries with fallback models; if all options are exhausted, reduce scope (use `quick_query`) or wait for quota reset.\n\n## Contributing\n\nRead the [Contributing Guide](./CONTRIBUTING.md) to get started.\n\nQuick links:\n- [Development setup](./CONTRIBUTING.md#development-setup)\n- [Running tests](./CONTRIBUTING.md#running-tests)\n- [Code guidelines](./CONTRIBUTING.md#code-guidelines)\n- [Submitting changes](./CONTRIBUTING.md#submitting-changes)\n\n## License\n\n[BSD-3-Clause License](./LICENSE.md)\n\n---\n\n<p align=\"center\">\n  Made with ♡ for the AI-assisted dev community\n</p>\n",
  "bytes": 14306,
  "sha": "18e8090e9543390e0b94cbae9bbefb9278424d5944ee973e0d1880a2f95d97d7",
  "repo_slug": "capybearista/gemini-researcher",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_capybearista_gemini_researcher_1c392337/readme"
}