gemini-mcp-tool

Implements a three-layer bridge pattern that translates incoming MCP protocol requests into Gemini CLI commands and marshals responses back through the MCP SDK. The server uses @modelcontextprotocol/sdk to handle MCP protocol handshakes, tool registration, and message routing, then spawns Gemini CLI processes as child processes to execute analysis tasks. This architecture decouples the MCP client (Claude Desktop) from direct Gemini CLI dependency, enabling seamless integration without modifying either system.

Implements a file reference system using @ prefix syntax that enables users to pass file and directory paths directly into Gemini analysis prompts. The system parses @-prefixed tokens in user input, resolves them to actual file system paths, reads file contents, and injects them into the Gemini CLI command as context. Supports single files (@src/main.js), directories (@.), and configuration files (@package.json), with automatic path resolution relative to the current working directory. This abstraction allows users to reference files without manually copying/pasting content.

Manages the lifecycle of Gemini CLI subprocess invocations, including spawning processes with appropriate arguments, capturing stdout/stderr, handling timeouts, and cleaning up resources. The system uses Node.js child_process module to spawn Gemini CLI with the appropriate command and arguments, sets up event handlers for process completion, implements timeout logic to prevent hung processes, and ensures resources are cleaned up even if requests fail. This abstraction isolates the MCP layer from subprocess management complexity.

Uses TypeScript and Zod for end-to-end type safety across the MCP request-response pipeline. Tool parameters are defined as Zod schemas that validate incoming requests at the MCP layer, ensuring type correctness before passing data to Gemini CLI. TypeScript provides compile-time type checking for internal functions and data structures, while Zod provides runtime validation for untrusted input from MCP clients. This dual-layer approach prevents type-related bugs and provides clear error messages when validation fails.

Provides a safe code execution environment by delegating execution to Gemini's built-in sandbox capabilities rather than running code locally. When users invoke the sandbox-test tool with code snippets, the system passes the code to Gemini CLI with sandbox mode enabled, which executes the code in an isolated environment and returns execution results (stdout, stderr, exit codes). This approach avoids local process spawning security risks and leverages Gemini's managed sandbox infrastructure for resource isolation and timeout enforcement.

Enables users to select between multiple Gemini models (gemini-2.5-flash, gemini-pro, gemini-nano) for different analysis tasks, with the system routing requests to the specified model via Gemini CLI. The tool accepts a model parameter that is passed directly to the Gemini CLI invocation, allowing users to trade off between speed (flash), capability (pro), and cost/latency (nano). Model selection is transparent to the MCP layer — the system simply forwards the model parameter to the CLI and returns results from the selected model.

Provides two interaction modes for users: natural language commands (e.g., 'ask gemini to analyze @file') and structured slash commands (e.g., '/analyze prompt:@file', '/sandbox prompt:code'). The system parses incoming requests to detect slash command syntax, extracts parameters, and routes them to the appropriate tool handler. Natural language commands are passed directly to Gemini for interpretation. This dual interface accommodates both conversational and structured workflows without requiring users to switch tools.

Registers available tools (ask-gemini, sandbox-test, /analyze, /sandbox, /help, /ping) with the MCP server and advertises their capabilities, parameters, and descriptions to the MCP client (Claude Desktop). The system uses the @modelcontextprotocol/sdk to define tool schemas with Zod validation, enabling Claude to understand what parameters each tool accepts and provide autocomplete/validation. Tool registration happens at server startup and is static — tools cannot be dynamically added or removed without restarting the server.

Handles streaming responses from Gemini CLI for long-running analysis tasks, allowing results to be streamed back to the MCP client as they become available rather than buffering the entire response. The system captures Gemini CLI stdout in chunks, formats them as MCP response messages, and sends them incrementally to Claude Desktop. This enables users to see partial results while analysis is still running, improving perceived responsiveness for large file analysis or complex reasoning tasks.

Implements structured error handling that captures failures from Gemini CLI execution, formats them as MCP error responses with diagnostic information, and returns them to the client. When Gemini CLI fails (missing authentication, invalid model, file not found, etc.), the system captures stderr, exit codes, and command context, then formats them as MCP error messages with actionable diagnostic information. This enables users to understand why analysis failed and how to fix it without debugging CLI output directly.

Provides a /ping command that tests connectivity between Claude Desktop and the Gemini MCP server, and between the server and Gemini CLI. The ping handler sends a test message through the full request-response pipeline and returns latency metrics and status information. This enables users to verify that the integration is working correctly before attempting analysis, and to diagnose connectivity issues if analysis requests fail.

Provides a /help command that displays Gemini CLI documentation, available commands, and usage examples directly within Claude Desktop. The system invokes Gemini CLI with the --help flag, captures its output, and returns it formatted as an MCP response. This enables users to learn about Gemini CLI capabilities without leaving Claude or consulting external documentation.