How choplin/mcp-gemini-cli works
Project type and purpose
• This is an open-source CLI “MCP server” wrapper around Google’s Gemini CLI.
• It exposes three “tools” (googleSearch, chat, analyzeFile) via the Model Context Protocol (MCP) so that AI assistants can invoke Gemini’s multimodal capabilities.
File structure
• Top-level files:
– index.ts: the main entry point and command dispatcher
– package.json, bun.lock, biome.json, tsconfig.json, .lefthook.yml, .markdownlintignore, .npmignore, .gitignore
• tests/integration/tools.test.ts: end-to-end tests for each tool
• No separate “frontend” or “backend” directories—this is a single CLI service.
README for additional insights
• Confirms three MCP tools, needed external dependency (Gemini CLI installed or invoked via npx)
• Shows quick-start commands, installation options (npx vs. bun run), and usage examples
• Mentions Bun as the runtime and standard build/test/lint scripts
a. Main components
1. MCP Client (e.g., Claude Desktop or any MCP-compatible client)
2. mcp-gemini-cli server process (index.ts running under Bun or npx)
– Tool Dispatcher
– Tool Implementations: googleSearch, chat, analyzeFile
3. External Gemini CLI binary (invoked via gemini command or npx mcp-gemini-cli --allow-npx)
4. Filesystem (for analyzeFile reads)
5. Tests (integration tests—optional to show separately)
b. Relationships & interactions
• MCP Client → (STDIN/STDOUT or IPC) → mcp-gemini-cli
• Dispatcher maps incoming MCP JSON requests to one of the three tool functions
• Each tool function spawns or calls the Gemini CLI process with appropriate flags
• Gemini CLI executes search/chat/analysis, returns output (text or JSON)
• mcp-gemini-cli captures output, reformats it in MCP response schema, sends back to the client
• analyzeFile also interacts with the local file system to read binary/text data
c. Architectural patterns & design principles
• CLI server pattern: single entrypoint + command dispatcher
• Tool abstraction: each “tool” is a pure function implementing a well-defined interface
• Process isolation: external Gemini CLI called as a subprocess (shell out)
• Minimal layering: Request parsing → Tool execution → Response formatting
d. Relevant technologies/frameworks
• Bun runtime or Node.js via npx
• TypeScript (index.ts)
• Model Context Protocol (MCP) JSON messaging over STDIO/IPC
• External Gemini CLI tool
• Testing: Bun’s built-in test runner for integration tests