DOCSEARCHbyAlgolia
Submit Docs

gemini-mcp-tool

repository·main·Indexed 25 days ago

https://github.com/jamubc/gemini-mcp-tool

An MCP server that integrates AI assistants, such as Claude, with the Gemini CLI or Antigravity CLI. It enables the use of Gemini's large token window for analyzing codebases and files via @ syntax, provides a sandbox mode for safe code execution, and supports models including Gemini-2.5-pro, Gemini-2.5-flash, and Flash-8B.

Tokens
16.6K
Snippets
47
Records
108
Agent score
80%

What's inside gemini-mcp-tool

  1. Overview of Gemini MCP Tool

    main

    Gemini MCP Tool connects the Gemini CLI to the Model Context Protocol (MCP) ecosystem. It allows developers to leverage Google's Gemini models within any client that supports the standardized MCP protocol, specifically optimized for use with Claude Code.

    Key Features:

    • MCP Standard Compliance: Built on and tested with the MCP protocol; benchmarked with Claude Code.
    • Natural File Editing: Supports @filename integration to direct model focus.
    • Model Selection: Choose between Gemini-2.5-Pro and Gemini-2.5-Flash using natural language.
    • No Extra Keys: Does not require additional API keys beyond the existing Gemini/Google environment.
    • Native Integrations: Designed to work with existing tools rather than reinventing them.

  2. When to use the ask-gemini tool

    main

    AI clients like Claude will automatically decide to invoke the ask-gemini tool based on the context of your request. You can trigger this workflow manually or rely on the client to identify these use cases:

    • Comparative Analysis: When you need different AI perspectives to validate a conclusion or idea.
    • Leveraging Extra Tools: When you want to utilize Gemini's specific search and memory functions.
    • Code Review & Big Changes: When you need a second opinion on complex implementations or large-scale code changes.
    • Creative Problem Solving: For brainstorming, ideation, and exploring new directions.

  3. How the gemini-mcp-tool integrates with AI clients

    main

    The gemini-mcp-tool acts as a bridge between MCP-compliant AI clients (like Claude) and the Gemini-CLI. When an AI client determines that Gemini's capabilities are needed, it invokes the ask-gemini tool. The tool then spawns a Gemini-CLI process to execute the request and returns the response back to the AI client, which then provides a summary to you.

    Workflow Lifecycle:

    1. User Trigger: You prompt your AI client (e.g., Claude) with a request that requires Gemini (e.g., "ask gemini...").
    2. Tool Invocation: The AI client invokes the ask-gemini tool provided by the gemini-mcp-tool.
    3. Process Spawning: The gemini-mcp-tool spawns the Gemini-CLI.
    4. Context Access: The Gemini-CLI can read project files (referenced via @Files) to gain context.
    5. Response Loop: Gemini-CLI returns a response to the gemini-mcp-tool, which passes it to the AI client, which finally presents a summary to you.

    Key Integration Points:

    • AI Client (e.g., Claude): Decides when to use the tool and manages the conversation.
    • gemini-mcp-tool: The MCP server implementation that handles the tool logic.
    • Gemini-CLI: The underlying engine that performs the actual interaction with Gemini.
    • Project Files: The tool allows Gemini to read your local files to provide context-aware answers.

  4. Available Gemini Models

    main

    The tool supports different Gemini models via the default Gemini CLI backend. Choose a model based on your task complexity and context requirements:

    • Gemini-2.5-pro

      • Best for: Complex analysis, large codebases, architectural reviews, and stronger reasoning.
      • Context Window: 2M tokens (~500k lines of code).
      • Trade-off: Slower speed.

    • Gemini-2.5-flash

      • Best for: Quick responses, routine tasks, fast code reviews, and simple explanations.
      • Context Window: 1M tokens (~250k lines of code).
      • Trade-off: Faster speed.

    • Flash-8B

      • Best for: Simple, repetitive tasks and quick fixes.
      • Context Window: 1M tokens (~250k lines of code).
    IMPORTANT

    Model selection applies to the Gemini CLI backend. If using the experimental Antigravity CLI (agy) backend, the system runs in print-mode as Gemini 3.5 Flash only and ignores model selection settings.

  5. Compare Gemini CLI and Antigravity CLI (agy) capabilities

    main

    When moving from the gemini CLI to agy, be aware of the following behavioral changes that affect programmatic integration:

    FeatureGemini CLIAntigravity CLI (agy)
    Commandgeminiagy
    One-shot prompt-p/--prompt (prints to stdout)-p/--print (may write nothing to stdout in 1.0.x, especially in headless/Windows)
    Model selection-m <model>--model (Note: -p is hardcoded to Gemini 3.5 Flash; switching models in -p may hang)
    @file inliningInlines @path contents into promptNot confirmed; agent typically uses its own tools
    Sandbox-s/--sandbox--sandbox (effectively unsandboxed in -p mode)
    Approval modes--approval-mode {default,auto_edit,yolo,plan}--dangerously-skip-permissions (is a no-op in -p mode)
    Sessions--session-id <id>, --resume--conversation <id>, --continue (--continue is global, not per-workspace)
    Output format--output-format json--output-format json (not reliably present in 1.0.x)
    AuthOAuth / API keyOS credential store; use agy -i to log in
    TranscriptsN/A (stdout is source of truth)JSONL transcripts in ~/.gemini/antigravity-cli/brain/...

  6. Understand Sandbox Mode limitations and safety features

    main

    The Sandbox environment is highly restricted to ensure safety. When running code in this mode, be aware of the following constraints:

    Safety Features:

    • Isolated Execution: The code has no access to your local file system.
    • No Network: The code cannot make external network requests.
    • Resource Limits: CPU and memory are constrained.
    • Time Limits: Prevents infinite loops from hanging the system.

    Technical Limitations:

    • Execution Time: Maximum of 30 seconds.
    • Memory Limit: Maximum of 512MB.
    • No File System/Network: As noted in safety features, these are strictly prohibited.

  7. Handle @file references securely and deterministically

    main

    The tool uses the @file syntax (e.g., @src/main.ts explain this) to include file contents in prompts. To ensure this works reliably across different backends (like agy) and remains secure, the tool performs the following:

    1. Security Guard: It calls assertSafeFileReferences() to reject any @ references that attempt to escape the project root (preventing path traversal).
    2. Manual Resolution: For the agy backend, instead of relying on the agent to read the file, the tool manually resolves the path, reads the file content, and embeds it directly into the prompt. This ensures the output is deterministic and the security guard remains active in the data path.

  8. Configure security and sandboxing for the tool

    main

    Users can attempt to pass sandboxing and approval flags, but their behavior depends on the backend:

    • Gemini CLI: Supports standard sandboxing and interactive approval gates.
    • Antigravity CLI (agy):
      • The --sandbox flag is supported but provides limited isolation in print mode (-p), as the agent may execute tools autonomously.
      • Approval modes (e.g., yolo, plan) are largely ineffective in print mode because there is no interactive gate to skip.

    Recommendation: When using the agy backend, treat tool execution as potentially unsandboxed and be aware that the tool may not be able to honor strict isolation requests.

  9. Manage tokens and select Gemini models

    main

    Choose the appropriate Gemini model based on the complexity and size of your task to manage token limits effectively:

    • Quick tasks: Use Flash (supports up to 1M tokens).
    • Full analysis: Use Pro (supports up to 2M tokens) for large codebases.
    • Simple queries: Use Flash-8B.

    Efficiency Tip: Avoid including dependencies. Instead of @node_modules/**/*.js, use @src/**/*.js @package.json to provide only the necessary source and manifest context.

  10. Understand the differences between Gemini CLI and Antigravity CLI (agy)

    main

    When migrating from the original Gemini CLI to the Antigravity CLI (agy), several core behaviors change that affect how the gemini-mcp-tool operates:

    • Output Contract: Unlike the Gemini CLI, agy -p (print mode) may exit with code 0 but produce empty stdout. The tool handles this by reading the conversation transcript from on-disk JSONL or SQLite files.
    • Model Selection: In agy print mode, model selection is effectively disabled. It is hardcoded to Gemini 3.5 Flash (High). Passing a different --model flag in print mode can cause the process to hang.
    • File Referencing (@file): While the Gemini CLI inlines file contents into the prompt, agy is agent-first and may attempt to read files itself. To maintain determinism and security, the tool manually resolves and embeds @file contents into the prompt before sending it to agy.
    • Security & Sandboxing: The --sandbox flag and approval modes (like yolo) provide weaker guarantees on the agy backend. In print mode (-p), the agent may execute filesystem and network operations with user privileges without an interactive approval gate.
    • Session Management: agy --continue resumes the most recent global conversation rather than a workspace-specific one. Concurrent runs in different workspaces may interfere with each other.
    • Installation & Auth: agy is a Go binary (not an npm package) typically located in ~/.local/bin/ (Unix) or %LOCALAPPDATA%\Antigravity\ (Windows). Authentication is handled via agy -i using the OS credential store.

  12. Support the development of Gemini MCP Tool

    main

    Gemini MCP Tool is an open-source project. You can support its long-term health and development through financial contributions or community involvement.

    Financial Support

    • GitHub Sponsors: The preferred method for steady, recurring support. Higher tiers may include benefits such as having your name or company logo featured in the main README and on the project website.
    • Ko-fi: An alternative way to provide one-time support.

    Community Contributions

    If you cannot contribute financially, you can help the project by:

    • Starring the Repo: Increases visibility to attract new users.
    • Reporting Issues: Submitting detailed bug reports to help find and fix issues.
    • Suggesting Features: Providing ideas to shape the project's roadmap.
    • Improving Docs: Writing, editing, or translating documentation.