gemini-mcp-tool

Implements a three-layer bridge pattern that translates incoming MCP protocol requests into Gemini CLI commands and marshals structured responses back through the MCP SDK. The server uses @modelcontextprotocol/sdk to handle MCP protocol handshakes, tool registration, and response serialization, while spawning Gemini CLI processes as child processes to execute analysis tasks. This architecture decouples the MCP client (Claude Desktop) from the Gemini CLI runtime, enabling async request handling and graceful error propagation.

Implements a file reference system using @ prefix notation (e.g., @src/main.js, @., @package.json) that resolves file paths and directory structures, then passes them to Gemini CLI for multimodal processing. The system parses @ tokens from user prompts, validates file existence, and constructs Gemini CLI arguments that include file content or directory trees. This enables users to reference local files directly in natural language prompts without manual copy-paste, leveraging Gemini's ability to process large file contexts in a single request.

Captures Gemini CLI exit codes, stdout, and stderr, interpreting them to construct meaningful error messages that are returned through the MCP protocol. The system treats non-zero exit codes as failures, extracts error details from stderr, and wraps them in MCP error responses. This approach provides visibility into Gemini CLI failures without requiring users to debug CLI output directly, though error messages depend on Gemini CLI's error formatting.

Provides a sandbox-test tool that routes code snippets to Gemini's isolated execution environment, allowing safe testing and validation of code without running it locally. The system accepts code input via the /sandbox slash command or sandbox-test tool, passes it to Gemini CLI with sandbox execution flags, and returns execution results including stdout, stderr, and exit codes. This leverages Gemini's built-in sandboxing to prevent malicious code execution while enabling rapid code testing within the Claude workflow.

Exposes Gemini analysis capabilities through two complementary interfaces: natural language tool calls (ask-gemini tool) and structured slash commands (/analyze, /sandbox, /help, /ping). The MCP server registers both tool definitions in the MCP protocol, allowing Claude to invoke either interface based on context. Natural language tools enable flexible, conversational analysis requests, while slash commands provide explicit, structured invocation for power users. Both routes converge on the same underlying Gemini CLI execution logic, providing consistency while supporting different user preferences.

Supports dynamic selection between multiple Gemini model variants (gemini-2.5-flash, gemini-pro, gemini-nano) by passing model selection flags to the Gemini CLI. The system allows users to specify which model to use for analysis tasks, enabling trade-offs between speed (flash), capability (pro), and cost/latency (nano). Model selection is passed through MCP tool parameters or environment configuration, and the MCP server constructs appropriate Gemini CLI arguments based on the selected model.

Uses Zod schema validation to define tool parameters and validate inputs before passing them to Gemini CLI. The MCP server registers tools with structured schemas (ask-gemini, sandbox-test, etc.) that specify required parameters, types, and constraints. When Claude invokes a tool, the MCP server validates the parameters against the Zod schema, returning validation errors if parameters are malformed. This ensures that only valid inputs reach the Gemini CLI, reducing downstream errors and improving user experience.

Provides /ping and /help slash commands that enable users to verify MCP server connectivity and understand available tools without executing analysis tasks. The /ping command sends a test message to the Gemini CLI and returns connection status, confirming that the MCP server, Gemini CLI, and API credentials are all functional. The /help command displays available tools, their parameters, and usage examples. These diagnostic tools reduce troubleshooting time and provide self-service documentation.

Manages Gemini CLI as child processes spawned asynchronously for each MCP tool invocation, using Node.js child_process APIs to handle subprocess lifecycle, I/O streams, and exit code handling. The system spawns a new Gemini CLI process per request, captures stdout and stderr, waits for process completion, and returns results through the MCP protocol. This architecture enables concurrent requests (each with its own process) and isolates failures to individual requests without affecting the MCP server.

Implements the entire MCP server in TypeScript using the @modelcontextprotocol/sdk, providing compile-time type checking for tool definitions, request handlers, and response objects. The system uses TypeScript interfaces to define tool schemas, request/response types, and error objects, catching type mismatches at build time rather than runtime. This approach reduces bugs related to parameter mismatches and enables IDE autocomplete for MCP protocol interactions.

Supports configuration of Gemini API credentials and model selection through environment variables, allowing users to customize the MCP server behavior without modifying source code. The system reads environment variables (e.g., GEMINI_API_KEY, GEMINI_MODEL) at startup and passes them to the Gemini CLI as arguments or environment variables. This approach enables deployment flexibility — the same MCP server binary can be deployed to different environments with different configurations.