gemini-mcp-tool: Putting Gemini's Token Window Behind Claude Code

The context-window handoff problem gemini-mcp-tool targets

The README frames the goal narrowly: use Gemini's analysis capability inside Claude Code to save tokens and analyze large files. That is a context-budget argument, not a capability argument. If you are working in an assistant whose context fills up on a large file or a directory listing, you have two options: chunk the file yourself, or delegate the reading to a model that will accept more of it in one call. This project implements the second option.

The audience is specific. You need an MCP-capable client (Claude Code or Claude Desktop are the two the README configures), Node.js v16 or higher, and a working Gemini-family CLI on the same machine. The server itself does not talk to a Google API directly. It is a wrapper: your assistant calls a tool, the tool invokes a CLI, and the CLI's output comes back. That design choice is why the project's biggest headline is a CLI retirement rather than a feature.

The README's own phrasing for the pitch is that you can "Ask gemini natural questions, through claude or Brainstorm new ideas in a party of 3." The second half is the more honest description of what this is: a way to get a second model's read on the same material without leaving the first model's interface.

How the server, the tools and the @ syntax fit together

The repository is a TypeScript package with a single binary entry. package.json declares "bin": { "gemini-mcp": "dist/index.js" }, main as dist/index.js, and type as module, so the server runs as an ESM Node process. Dependencies are thin: the MCP SDK, zod plus zod-to-json-schema for tool schemas, chalk for terminal output, and prismjs and d3-shape, which suggests some rendering happens in the terminal path rather than in the model path.

The tool surface is small. ask-gemini takes a required prompt plus optional model and sandbox arguments; the README states model defaults to gemini-2.5-pro and that sandbox set to true runs in sandbox mode. A second tool, sandbox-test, is described in the truncated README as safely executing something, but the text cuts off before the parameters are listed, so I would not guess at its signature.

The mechanism for file access is string-level, not retrieval-level. You write @src/main.js or @. inside the prompt, and the CLI resolves those references on its side. The MCP server is passing a prompt through, not indexing your repository. That matters for expectations: there is no embedding store, no chunking strategy, no cache. If the CLI cannot see a path, the server cannot either.

Data flow, end to end: assistant decides to call ask-gemini, the server spawns the selected backend binary with the prompt, the CLI runs (up to GEMINI_MCP_TIMEOUT minutes, default 45), and stdout is returned as the tool result. The README notes that for the agy backend, replies come from agy's stdout with transcript recovery only as a fallback.

Installing gemini-mcp-tool and a first real analysis run

The README gives a one-line setup for Claude Code. It registers the server under the name gemini-cli and runs the published package through npx. Nothing is installed globally, so the first invocation downloads the package.

claude mcp add gemini-cli -- npx -y gemini-mcp-tool

On Windows the README says to use -- y instead of -y, because of how the argument separator is parsed:

claude mcp add gemini-cli -- npx -- y gemini-mcp-tool

After that, type /mcp inside Claude Code. You should see the gemini-cli MCP listed as active. If you already have the server configured in Claude Desktop, the README offers an import path instead of a manual re-add:

claude mcp add-from-claude-desktop

For a manual Claude Desktop configuration, the README shows this shape in claude_desktop_config.json. On macOS that file lives at ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows at %APPDATA%\Claude\claude_desktop_config.json, and on Linux at ~/.config/claude/claude_desktop_config.json.

{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool"]
    }
  }
}

If you installed the package globally, the README swaps the command for the binary name directly: "command": "gemini-mcp" with no args.

The first real use is a prompt in natural language. The README's examples include asking gemini to analyze @src/main.js, or to summarize @. for the current directory. You do not call the tool by name; the assistant decides to. In Claude Code the README also mentions typing /gemini-cli to populate commands in the interface. Expect the call to be slow relative to a normal tool: the server is waiting on a full CLI run, and the default ceiling is 45 minutes.

The Antigravity migration is now the project's real constraint

The most consequential thing in the README is not a feature. It is a retirement notice. The README states that on 2026-06-18 Google retired the Gemini CLI for free, Google AI Pro and Google AI Ultra users, plus individual Gemini Code Assist and GitHub-org users, and that the successor is the Antigravity CLI, invoked as agy. From that date, the tool selects the agy backend automatically. The release history lines up: v1.1.8 is titled "Antigravity CLI (agy) backend" and is dated 2026-06-18.

If you are in an affected tier, the README's instruction is to install agy with a curl-to-bash script from antigravity.google and run it once to sign in. Nothing else changes. If you are on an enterprise or Standard licence, or using a paid API key, the README says your Gemini CLI access is unaffected, and you keep it by setting GEMINI_MCP_BACKEND=gemini on the MCP server.

Three environment variables govern behaviour. GEMINI_MCP_BACKEND accepts gemini or agy/antigravity, and when unset uses the date-aware default. AGY_CLI_PATH gives the full path to the agy binary if it is not on the server's PATH. GEMINI_MCP_TIMEOUT sets the overall CLI run timeout in minutes, default 45.

The README is unusually candid that the agy backend is experimental, and lists exactly why: print mode is Gemini 3.5 Flash-only, replies come from agy's stdout with transcript recovery only as a fallback, and tool execution is not sandboxed in -p. It also states that the tool emits a notice when a requested model or sandbox cannot be honoured, and surfaces agy's own quota and auth errors verbatim. That last point is a design position worth noting: the server does not translate backend errors into its own vocabulary, so what you see in the assistant is what the CLI printed.

Where this is the wrong tool, and what to use instead

The clearest failure mode is the sandbox flag. The README documents sandbox as a supported argument on ask-gemini, and separately documents that in agy print mode tool execution is not sandboxed. If your workflow depends on the sandbox actually containing execution, the documentation says the requested sandbox may not be honourable on the default backend, and the tool will tell you so rather than silently pretending. Treat sandbox as a request, not a guarantee.

A second limitation is model selection. On the agy backend, print mode is Gemini 3.5 Flash-only per the README, so passing model to ask-gemini may not do what you expect. The default model documented for the tool is gemini-2.5-pro, which is a Gemini CLI era default; the two do not line up on the new backend.

A third is that this is a local CLI wrapper, not a hosted connector. It needs Node, a CLI binary, and an authenticated session on the same machine as the MCP server. Anything that runs your assistant in an environment without that CLI will not work.

For a real alternative, consider the MCP servers that talk to a provider's HTTP API directly rather than shelling out to a CLI. The difference in approach is where the failure lives. An API-backed server authenticates with a key, returns structured JSON, and its versioning is tied to the API contract. gemini-mcp-tool instead inherits the CLI's lifecycle, which is exactly what the retirement notice demonstrates: when Google changed the CLI, every user of this server had to install a different binary or set an environment variable. If you want stability across provider-side tooling changes, the API route has fewer moving parts. If you specifically want the CLI's file-resolution behaviour and its @ syntax, this project is the thin layer that exposes it.

Maintenance signals, licence and what an upgrade costs you

The repository is not archived. The last push was on 2026-07-21, roughly two months before this writing, and the most recent release is v1.1.8 on 2026-06-18. There is also a v1.2.0-beta.1 dated 2026-05-30, which predates the stable v1.1.8 release despite the higher version number, so do not read the beta tag as the newer line.

package.json declares "license": "MIT" and the README carries an MIT badge, but the repository metadata reports the licence as NOASSERTION. That mismatch is worth resolving yourself before you depend on the package in a commercial setting: read the LICENSE file at the repository root, since that is the file npm ships per the files field. I am not in a position to give legal advice, and this is a metadata discrepancy rather than a legal conclusion.

The upgrade cost is concentrated in the backend switch. Because the default backend is date-aware, a machine that was working before 2026-06-18 can change behaviour without you changing any configuration, unless you pin GEMINI_MCP_BACKEND explicitly. The README's own table makes that the first thing to check when something breaks: an unset value means the default is computed, not fixed.

For local development the package ships scripts worth knowing about. npm run build runs tsc, npm start runs dist/index.js, and npm run doctor runs scripts/doctor.mjs, with a doctor:judge variant. Tests are split into unit, integration and e2e via scripts/run-tests.mjs. If you are debugging a backend mismatch, the doctor script is the project's own diagnostic path rather than something you have to assemble from logs.

Editorial conclusion

Adopt it if you already run Claude Code or Claude Desktop and want a second model to read files too large to paste into your main context, and if you can accept an experimental Antigravity backend or pin GEMINI_MCP_BACKEND=gemini on an enterprise tier. Skip it if you need a sandboxed agent loop, since the README states tool execution is not sandboxed in agy print mode, or if you want a hosted connector rather than a local CLI wrapper. Before adopting, run the one-line add, confirm the server appears in /mcp, then run npm run doctor from a clone and check which backend it actually resolves to on your machine.

Frequently asked questions

Official sources

1. Issues
2. jamubc/gemini-mcp-tool on GitHub
3. Project website
4. README
5. Releases