Skip to main content
Glama

Gemini MCP Tool

GitHub Release npm version npm downloads License: MIT Open Source

📚 View Full Documentation - Search me!, Examples, FAQ, Troubleshooting, Best Practices

This is a simple Model Context Protocol (MCP) server that allows AI assistants to interact with the Gemini CLI. It enables the AI to leverage the power of Gemini's massive token window for large analysis, especially with large files and codebases using the @ syntax for direction.

  • Ask gemini natural questions, through claude or Brainstorm new ideas in a party of 3!

TLDR: Claude + Gemini(Google Antigravity CLI)

Goal: Use Gemini's powerful analysis capabilities directly in Claude Code to save tokens and analyze large files.

Related MCP server: DeepView MCP

Prerequisites

On 2026-06-18, Google retired the Gemini CLI for free, Google AI Pro, and Google AI Ultra users (and individual Gemini Code Assist / GitHub-org users). Its successor is the Antigravity CLI (agy). See Google's announcement.

From 2026-06-18 this tool selects the agy backend automatically. If you are on an affected tier, just install agy:

curl -fsSL https://antigravity.google/cli/install.sh | bash   # macOS / Linux

Then run agy once to sign in. Nothing else to change.

Enterprise / Standard-license or paid-API-key user? Your Gemini CLI access is unaffected by the retirement. To keep using it, set one env var on the MCP server:

GEMINI_MCP_BACKEND=gemini

Variable

Purpose

GEMINI_MCP_BACKEND

gemini or agy/antigravity. Unset uses the date-aware default (agy from 2026-06-18).

AGY_CLI_PATH

Full path to the agy binary if it isn't on the server's PATH.

GEMINI_MCP_TIMEOUT

Overall CLI run timeout in minutes (default 45).

The agy backend is experimental: print mode is Gemini 3.5 Flash-only, replies come from agy's stdout (transcript recovery only as a fallback), and tool execution isn't sandboxed in -p. The tool emits a notice when a requested model/sandbox can't be honored, and surfaces agy's own errors (quota, auth) verbatim. Full analysis: docs/migration/antigravity-cli.md.

Before using this tool, ensure you have:

  1. Node.js (v16.0.0 or higher)

  2. Google Gemini CLI installed and configured

One-Line Setup

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

Use -- y instead of -y:

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

Verify Installation

Type /mcp inside Claude Code to verify the gemini-cli MCP is active.


Alternative: Import from Claude Desktop

If you already have it configured in Claude Desktop:

  1. Add to your Claude Desktop config:

"gemini-cli": {
  "command": "npx",
  "args": ["-y", "gemini-mcp-tool"]
}
  1. Import to Claude Code:

claude mcp add-from-claude-desktop

Configuration

Register the MCP server with your MCP client:

Add this configuration to your Claude Desktop config file:

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

For Global Installation

If you installed globally, use this configuration instead:

{
  "mcpServers": {
    "gemini-cli": {
      "command": "gemini-mcp"
    }
  }
}

Configuration File Locations:

  • Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Linux: ~/.config/claude/claude_desktop_config.json

After updating the configuration, restart your terminal session.

Example Workflow

  • Natural language: "use gemini to explain index.html", "understand the massive project using gemini", "ask gemini to search for latest news"

  • Claude Code: Type /gemini-cli and commands will populate in Claude Code's interface.

Usage Examples

With File References (using @ syntax)

  • ask gemini to analyze @src/main.js and explain what it does

  • use gemini to summarize @. the current directory

  • analyze @package.json and tell me about dependencies

General Questions (without files)

  • ask gemini to search for the latest tech news

  • use gemini to explain div centering

  • ask gemini about best practices for React development related to @file_im_confused_about

Using Gemini CLI's Sandbox Mode (-s)

The sandbox mode allows you to safely test code changes, run scripts, or execute potentially risky operations in an isolated environment.

  • use gemini sandbox to create and run a Python script that processes data

  • ask gemini to safely test @script.py and explain what it does

  • use gemini sandbox to install numpy and create a data visualization

  • test this code safely: Create a script that makes HTTP requests to an API

Tools (for the AI)

These tools are designed to be used by the AI assistant.

  • ask-gemini: Asks Google Gemini for its perspective. Can be used for general questions or complex analysis of files.

    • prompt (required): The analysis request. Use the @ syntax to include file or directory references (e.g., @src/main.js explain this code) or ask general questions (e.g., Please use a web search to find the latest news stories).

    • model (optional): The Gemini model to use. Defaults to gemini-2.5-pro.

    • sandbox (optional): Set to true to run in sandbox mode for safe code execution.

  • sandbox-test: Safely executes code or commands in Gemini's sandbox environment. Always runs in sandbox mode.

    • prompt (required): Code testing request (e.g., Create and run a Python script that... or @script.py Run this safely).

    • model (optional): The Gemini model to use.

  • Ping: A simple test tool that echoes back a message.

  • Help: Shows the Gemini CLI help text.

Slash Commands (for the User)

You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).

  • /analyze: Analyzes files or directories using Gemini, or asks general questions.

    • prompt (required): The analysis prompt. Use @ syntax to include files (e.g., /analyze prompt:@src/ summarize this directory) or ask general questions (e.g., /analyze prompt:Please use a web search to find the latest news stories).

  • /sandbox: Safely tests code or scripts in Gemini's sandbox environment.

    • prompt (required): Code testing request (e.g., /sandbox prompt:Create and run a Python script that processes CSV data or /sandbox prompt:@script.py Test this script safely).

  • /help: Displays the Gemini CLI help information.

  • /ping: Tests the connection to the server.

    • message (optional): A message to echo back.

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on how to submit pull requests, report issues, and contribute to the project.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer: This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by Google.

Available Tools

5 tools
ask-geminiC

model selection [-m], sandbox [-s], and changeMode:boolean for providing edits

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesAnalysis request. Use @ syntax to include files (e.g., '@largefile.js explain what this does') or ask general questions
modelNoOptional model to use (e.g., 'gemini-2.5-flash'). If not specified, uses the default model (gemini-2.5-pro).
sandboxNoUse sandbox mode (-s flag) to safely test code changes, execute scripts, or run potentially risky operations in an isolated environment
changeModeNoEnable structured change mode - formats prompts to prevent tool errors and returns structured edit suggestions that Claude can apply directly
chunkIndexNoWhich chunk to return (1-based)
chunkCacheKeyNoOptional cache key for continuation

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must bear full burden. It mentions sandbox for safe testing but does not disclose whether edits are applied or if the tool is read-only. Behavioral traits like side effects or permissions are omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and somewhat cryptic with flags. It is concise but not well-structured or informative enough.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema, and no annotations, the description is too brief. It fails to explain core functionality, return values, or usage patterns, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description adds minimal value beyond mentioning flags, as the schema already explains parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description mentions options like model selection, sandbox, and changeMode, but does not clearly state the core action of the tool (asking Gemini). It is vague and fails to distinguish it from siblings like brainstorm or Help.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description lacks context about appropriate scenarios or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brainstormA

Generate novel ideas with dynamic context gathering. --> Creative frameworks (SCAMPER, Design Thinking, etc.), domain context integration, idea clustering, feasibility analysis, and iterative refinement.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesPrimary brainstorming challenge or question to explore
modelNoOptional model to use (e.g., 'gemini-2.5-flash'). If not specified, uses the default model (gemini-2.5-pro).
methodologyNoBrainstorming framework: 'divergent' (generate many ideas), 'convergent' (refine existing), 'scamper' (systematic triggers), 'design-thinking' (human-centered), 'lateral' (unexpected connections), 'auto' (AI selects best)auto
domainNoDomain context for specialized brainstorming (e.g., 'software', 'business', 'creative', 'research', 'product', 'marketing')
constraintsNoKnown limitations, requirements, or boundaries (budget, time, technical, legal, etc.)
existingContextNoBackground information, previous attempts, or current state to build upon
ideaCountNoTarget number of ideas to generate (default: 10-15)
includeAnalysisNoInclude feasibility, impact, and implementation analysis for generated ideas

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden and discloses key behaviors: dynamic context gathering, creative frameworks, domain integration, clustering, analysis, and iterative refinement. This gives a good sense of how the tool operates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a dash and list, keeping it concise and front-loading the purpose. Could be slightly more structured but effectively minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 8 parameters, no output schema, and no annotations, the description covers the main features and behaviors reasonably well. Missing some details like output format or limitations, but adequate for a creative tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all parameters described, so the description adds little beyond high-level context. The description mentions 'domain context integration' which aligns with the domain parameter, but does not deepen understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Generate novel ideas' (verb and resource) and lists creative frameworks and features, clearly distinguishing it from sibling tools like ask-gemini which is for Q&A.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for brainstorming sessions but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch-chunkA

Retrieves cached chunks from a changeMode response. Use this to get subsequent chunks after receiving a partial changeMode response.

ParametersJSON Schema
NameRequiredDescriptionDefault
cacheKeyYesThe cache key provided in the initial changeMode response
chunkIndexYesWhich chunk to retrieve (1-based index)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral burden. The word 'Retrieves' signals a read operation, and 'cached chunks' implies a non-destructive lookup from previously stored response data. It does not detail cache expiration or whether chunks can be re-fetched, but the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences deliver the core behavior and the intended usage context with no wasted words. The primary action is front-loaded and the follow-up guidance is immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives enough context for a simple two-parameter fetch tool: where the cacheKey comes from and when to call it. With no output schema, it could have clarified the response shape or chunk count, but the invocation path is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented. The description adds context about when the cacheKey/chunkIndex are used, but it does not provide substantial extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it retrieves cached chunks from a changeMode response. It also clarifies the tool's role as the follow-up mechanism for partial changeMode responses, making its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use this tool 'after receiving a partial changeMode response' and positions it as the way to get subsequent chunks. It does not mention exclusions or alternatives, but no directly competing sibling tool is apparent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

HelpC

receive help information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description should disclose behavior but only states the generic purpose; no details on side effects, permissions, or output are given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but lacks substance; it is not informative enough despite being concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description should provide more context (e.g., what help topics are covered), but it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%, meeting the baseline. The description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'receive help information' is vague and does not specify what kind of help or how it differs from sibling tools like ask-gemini.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives; no context or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pingC

Echo

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNoMessage to echo

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Echo' only restates the core action and implies the prompt is returned, but it does not state side effects, safety traits, or response format. For a trivial tool this is minimally acceptable, but it still lacks explicit behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is extremely concise, it is under-specified rather than efficiently structured. A single word without context is not a well-formed definition, and the conciseness is the result of omission rather than careful pruning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's low complexity, the description leaves out important context such as the intended use (e.g., connectivity test or echo of user input) and the fact that the given prompt will be returned. There is no output schema, so the description should clarify return behavior, but it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage with the description 'Message to echo' for the prompt parameter. The description 'Echo' adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is a single word, 'Echo', which names an action but does not specify the resource or what is echoed. It is not a complete statement of purpose and leaves ambiguity about whether it echoes the prompt parameter or something else. This is more like a vague fragment than a clear tool definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus any of the sibling tools. There is no mention of typical use cases, prerequisites, or exclusions. An agent receives no context to decide whether to call ping instead of ask-gemini or brainstorm.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.1.7
    • Removedtimeout-test
  2. 6 tool updates
    • First observedask-gemini
    • First observedbrainstorm
    • First observedfetch-chunk
    • First observedHelp
    • First observedping
    • First observedtimeout-test

TDQS

C2.8/5.0

Scored across 5 tools

Disambiguation4/5

Tools have distinct purposes: ask-gemini for general interaction with edit capability, brainstorm for creative idea generation, fetch-chunk for retrieving continuation of long responses. Some overlap in text generation but descriptions clarify boundaries.

Naming Consistency2/5

Naming is inconsistent: 'ask-gemini' and 'fetch-chunk' use hyphens, 'brainstorm' is one word, while 'Help' is capitalized and 'ping' is lowercase. No consistent verb_noun pattern across all tools.

Tool Count4/5

With 5 tools, the server covers core interaction, creative brainstorming, and chunk retrieval. Slightly thin but well-scoped for a focused Gemini assistant.

Completeness3/5

Covers basic chat, creative idea generation, and long response handling, but lacks tools for managing sessions, listing models, or more advanced capabilities. Moderate completeness for its scope.

Maintenance

ActivityInactive
ResponsivenessSlow

Related MCP Connectors

  • A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

  • A Model Context Protocol server for Wix AI tools

  • The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.

  • The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A server implementing the Model Context Protocol that enables AI assistants like Claude to interact with Google's Gemini API for text generation, text analysis, and chat conversations.
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that enables IDEs like Cursor and Windsurf to analyze large codebases using Gemini's extensive context window.
    65
    MIT
  • -
    license
    Not graded
    quality
    Not graded
    maintenance
    A server that allows interaction with Google's Gemini AI through the Gemini CLI tool using the Model Context Protocol, providing a standardized interface for querying Gemini with various options and configurations.
    -