gemini-mcp-tool: Bridging Claude Code and the Gemini CLI
MCP server that enables AI assistants to interact with Google Gemini CLI, leveraging Gemini's massive token window for large file analysis and codebase understanding
At a glance
- What is it?
- A Model Context Protocol server that lets an MCP client hand prompts and @-referenced files to a Gemini or Antigravity CLI backend. The design is small, the value is in the token economics, and the backend transition is the thing to check before you adopt it.
- Who is it for?
- Adopt it if you already run Claude Code or another MCP client and want a second model to read large files or whole directories through the @ syntax without pasting content into a prompt. Do not adopt it if you need sandboxed execution guaranteed, a fixed model identity, or a backend that will not change under you; the agy backend is documented as experimental, print mode is described as Gemini 3.5 Flash-only, and tool execution is not sandboxed in -p.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 56 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: context windows and the cost of one model doing everything
Every MCP client has a context budget, and large files eat it. The README frames the goal plainly: use Gemini's analysis capabilities inside Claude Code to save tokens and analyze large files. The mechanism for that is the Gemini CLI's @ syntax, which lets a prompt name a file or a directory instead of containing its contents. The README's own examples are `ask gemini to analyze @src/main.js and explain what it does` and `use gemini to summarize @. the current directory`. The directory form is the interesting one. A single @. reference asks the other side to walk the tree, so the calling assistant never has to serialize the repository into its own window. That is the whole pitch: offload reading, keep the conversation. The intended user is someone already inside an MCP client, most often Claude Code, who wants a second model's read on a codebase. It is not a general chat wrapper, and it is not a replacement for the Gemini CLI itself. It is a thin adapter that turns a CLI into a callable tool.
The two tools the assistant actually sees
The server exposes tools rather than a chat interface. The README documents `ask-gemini` with three fields: `prompt` (required), `model` (optional, defaulting to `gemini-2.5-pro`), and `sandbox` (optional, set to true for isolated execution). The prompt field is where the @ references go, and it is also where plain questions go; the README lists `ask gemini to search for the latest tech news` as a no-file case. A second tool, `sandbox-test`, is named in the README but its description is cut off in the supplied material, so its exact parameters cannot be confirmed here. The data flow is one hop in each direction. The MCP client calls the tool with a prompt string, the server invokes the CLI backend, the backend's stdout comes back as the tool result. The README says that on the agy backend replies come from stdout, with transcript recovery only as a fallback. That detail matters because it tells you the integration is not parsing structured output; it is reading a terminal stream and hoping the answer is in it.
Installation and the configuration keys that decide behaviour
The fastest path is one command: `claude mcp add gemini-cli -- npx -y gemini-mcp-tool`. On Windows the README instructs `claude mcp add gemini-cli -- npx -- y gemini-mcp-tool`, which is the same command with the flag split. For Claude Desktop the README gives a JSON block under `mcpServers` with `command` set to `npx` and `args` set to `["-y", "gemini-mcp-tool"]`; a global install swaps the command to `gemini-mcp`. Config file locations are listed per platform, including `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. There is also `claude mcp add-from-claude-desktop` if the Desktop config already exists. Three environment variables control the backend: `GEMINI_MCP_BACKEND` (`gemini` or `agy`/`antigravity`), `AGY_CLI_PATH` for a binary not on the server's PATH, and `GEMINI_MCP_TIMEOUT` for the overall CLI run timeout in minutes, default 45. Verification is `/mcp` inside Claude Code. Node.js v16.0.0 or higher is required.
The backend switch is the real configuration decision
The README states that on 2026-06-18 Google retired the Gemini CLI for free, Google AI Pro, and Google AI Ultra users, and for individual Gemini Code Assist and GitHub-org users, with the Antigravity CLI (`agy`) as successor. From that date the tool selects the `agy` backend automatically when `GEMINI_MCP_BACKEND` is unset. Installation of the successor is `curl -fsSL https://antigravity.google/cli/install.sh | bash`, followed by running `agy` once to sign in. Enterprise, Standard-license, and paid-API-key users are described as unaffected, and they keep the old path by setting `GEMINI_MCP_BACKEND=gemini` on the MCP server. This is a date-aware default, which is unusual and worth understanding before you debug anything: the same unmodified config can resolve to different backends depending on the calendar. If a prompt behaves differently after an upgrade, the backend is the first thing to check, not the model field.
What the agy backend does not do
The README labels the `agy` backend experimental and lists three constraints in one sentence. Print mode is Gemini 3.5 Flash-only. Replies come from `agy`'s stdout, with transcript recovery only as a fallback. Tool execution is not sandboxed in `-p`. Read those together and the picture is clear: a `model` value you pass in may not be honored, and a `sandbox: true` request may not be honored either. The README says the tool emits a notice when a requested `model` or `sandbox` can't be honored, and that it surfaces `agy`'s own errors, such as quota or auth failures, verbatim. The notice behaviour is the right call, because silent degradation would be worse. But a notice is not a guarantee. If your workflow depends on a specific model answering, or on risky code running in isolation, the agy path is the wrong one. The README points to `docs/migration/antigravity-cli.md` for the full analysis, which is where the specifics beyond this summary would live.
The licence field says NOASSERTION. The README badge says MIT
This is a discrepancy you should resolve before depending on the project. The repository metadata supplied here carries `NOASSERTION` for the licence, which is what a hosting platform reports when it cannot classify the licence file automatically. The README displays an MIT badge linking to opensource.org. Both can be true at once, for example if the licence text is present but not in a form the detector recognizes, or if the badge was added independently of the licence file. The practical consequence is that the permissive terms you might assume from the badge are not confirmed by the metadata. Check the LICENSE file in the repository directly. This is not legal advice, and if the distinction matters to your organisation, the file itself is the thing to read, not the badge and not this article. A one-line badge is not a licence grant.
Maintenance cost and the alternative you already have
The release history shows a project tracking a moving target: v1.1.7 on 2026-06-01, a v1.2.0-beta.1 prerelease on 2026-05-30, and v1.1.8 on 2026-06-18 whose release note is the `agy` backend itself. The last push recorded is 2026-07-21. That cadence is what you would expect from an adapter whose upstream dependency was retired and replaced within the same month. The maintenance cost to you is not the server code; it is the backend churn. Your config can be correct and still change behaviour when the default flips or when a beta lands. The obvious alternative is to skip the MCP layer and call the CLI directly from a shell, which removes a dependency but also removes the reason to use this: the MCP client cannot invoke a shell command as a tool without something in between. A second alternative is to keep everything in the calling assistant and use its own file-reading tools, which avoids a second vendor and a second auth flow but spends the context budget this project exists to save. The trade is explicit: one more moving part in exchange for not paying to read the repository.
Who should adopt it, and what to check first
Adopt it if you run an MCP client, you already have a working CLI backend, and your main use is pointing a second model at files and directories through @ references. The setup is one command and the tool surface is small enough to reason about. Do not adopt it if you need a pinned model, guaranteed sandboxing, or a stable backend identity across upgrades; the README's own description of the agy path rules those out. Before you commit, do three things in order. Confirm which backend your environment resolves to, since the default is date-aware and only the `GEMINI_MCP_BACKEND` variable overrides it. Confirm that the CLI you intend to use is installed and signed in, because the server does not manage auth. Then run `/mcp` inside Claude Code to verify the server is registered and active. If any of those three steps depends on a detail you cannot find in the README, the linked documentation site and `docs/migration/antigravity-cli.md` are where the project says the rest lives.
Editorial conclusion
Adopt it if you already run Claude Code or another MCP client and want a second model to read large files or whole directories through the @ syntax without pasting content into a prompt. Do not adopt it if you need sandboxed execution guaranteed, a fixed model identity, or a backend that will not change under you; the agy backend is documented as experimental, print mode is described as Gemini 3.5 Flash-only, and tool execution is not sandboxed in -p. Before rolling it out, confirm which backend your account actually resolves to by checking whether GEMINI_MCP_BACKEND is set, then run /mcp inside Claude Code to confirm the server is active.
Community notes