@danwahl/gemini-cli-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# gemini-cli-mcp
+
+A minimal MCP server that exposes [Gemini CLI](https://github.com/google-gemini/gemini-cli) as a single tool callable from Claude Code (or any MCP client).
+
+## How it works
+
+Claude Code sends prompts to this server via MCP. The server spawns `gemini -p "..."` in headless mode and returns the response. Gemini inherits your Google OAuth session — no API key required.
+
+```
+Claude Code ──MCP/stdio──▶ gemini-cli-mcp ──spawn──▶ gemini -p "..." --output-format json
+```
+
+## Prerequisites
+
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated:
+  ```sh
+  npm install -g @google/gemini-cli
+  gemini  # complete the OAuth login flow
+  ```
+
+## Installation
+
+### From source
+
+```sh
+git clone https://github.com/danwahl/gemini-cli-mcp
+cd gemini-cli-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+If installed via npm:
+
+```sh
+claude mcp add gemini npx @danwahl/gemini-cli-mcp
+```
+
+Or from source:
+
+```sh
+claude mcp add gemini node /absolute/path/to/gemini-cli-mcp/cli.js
+```
+
+Verify with `claude mcp list`.
+
+## Tool: `cli`
+
+| Parameter   | Type   | Required | Description |
+|-------------|--------|----------|-------------|
+| `prompt`    | string | yes      | Task or question to send to Gemini |
+| `cwd`       | string | yes      | Absolute path to working directory |
+| `model`     | string | no       | Model name or alias (see below). Omit to use Gemini CLI's default (`auto`). |
+| `sessionId` | string | no       | Resume a previous session. The session ID is returned in the structured output of each call. |
+
+### Structured output
+
+Each call returns structured content alongside the text response:
+
+```json
+{
+  "sessionId": "e80096bd-...",
+  "response": "Gemini's answer...",
+  "models": {
+    "gemini-2.5-flash-lite": 1399,
+    "gemini-3-flash-preview": 18635
+  },
+  "tools": {
+    "list_directory": 2
+  }
+}
+```
+
+`models` maps model name → total tokens used. `tools` maps tool name → call count (only present when Gemini used tools).
+
+### Model aliases
+
+These are passed directly to the CLI, which resolves them:
+
+| Alias        | Description |
+|--------------|-------------|
+| `auto`       | Default routing (pro or preview depending on settings) |
+| `pro`        | Complex reasoning tasks |
+| `flash`      | Fast, balanced — good for most tasks |
+| `flash-lite` | Fastest, for simple tasks |
+
+Or pass any concrete model name like `"gemini-2.5-pro"`.
+
+### What Gemini can do
+
+Gemini runs with `--approval-mode yolo`, giving it full tool access: read/write files, run shell commands, web search, and more. It operates in the `cwd` you specify.
+
+## Development
+
+```sh
+npm run build   # compile with tsdown
+npm test        # run unit tests
+```
+
+### Smoke test
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node cli.js
+```
+
+## Design
+
+One tool, no prompt wrappers. Claude Code is the orchestrator — it decides what to ask Gemini and how to phrase it. This server is a thin, reliable pipe between MCP and `gemini -p`.
+
+See [CLAUDE.md](./CLAUDE.md) for project conventions.

package/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./dist/index.js"

package/dist/index.js

@@ -0,0 +1,214 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { z } from "zod";
+
+//#region src/index.ts
+function buildGeminiArgs(prompt, model, sessionId, outputFormat = "json") {
+	const args = [
+		"-p",
+		prompt,
+		"--output-format",
+		outputFormat,
+		"--approval-mode",
+		"yolo"
+	];
+	if (model) args.push("--model", model);
+	if (sessionId) args.push("--resume", sessionId);
+	return args;
+}
+function parseGeminiOutput(stdout) {
+	const trimmed = stdout.trim();
+	if (!trimmed) return {
+		sessionId: null,
+		response: ""
+	};
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (parsed !== null && typeof parsed === "object" && "response" in parsed && typeof parsed.response === "string") {
+			const obj = parsed;
+			return {
+				sessionId: typeof obj.session_id === "string" ? obj.session_id : null,
+				response: obj.response,
+				stats: typeof obj.stats === "object" && obj.stats !== null ? obj.stats : void 0
+			};
+		}
+		return {
+			sessionId: null,
+			response: trimmed
+		};
+	} catch {
+		return {
+			sessionId: null,
+			response: trimmed
+		};
+	}
+}
+function extractStructuredOutput(output) {
+	const models = {};
+	const tools = {};
+	const stats = output.stats;
+	if (stats) {
+		if (stats.models && typeof stats.models === "object") {
+			for (const [name, modelStats] of Object.entries(stats.models)) if (modelStats && typeof modelStats === "object") {
+				const t = modelStats.tokens;
+				if (t && typeof t === "object" && typeof t.total === "number") models[name] = t.total;
+			}
+		}
+		if (stats.tools && typeof stats.tools === "object") {
+			const byName = stats.tools.byName;
+			if (byName && typeof byName === "object") {
+				for (const [name, toolStats] of Object.entries(byName)) if (toolStats && typeof toolStats === "object") {
+					const count = toolStats.count;
+					if (typeof count === "number") tools[name] = count;
+				}
+			}
+		}
+	}
+	return {
+		sessionId: output.sessionId,
+		response: output.response,
+		models,
+		tools
+	};
+}
+function runGemini(prompt, cwd, model, timeoutMs, sessionId) {
+	if (!existsSync(cwd)) return Promise.resolve({
+		output: {
+			sessionId: null,
+			response: ""
+		},
+		isError: true,
+		errorMessage: `Working directory does not exist: ${cwd}`
+	});
+	return new Promise((resolve) => {
+		const args = buildGeminiArgs(prompt, model, sessionId);
+		let child;
+		try {
+			child = spawn("gemini", args, {
+				cwd,
+				env: process.env
+			});
+		} catch (err) {
+			resolve({
+				output: {
+					sessionId: null,
+					response: ""
+				},
+				isError: true,
+				errorMessage: `Failed to spawn gemini: ${String(err)}. Is gemini-cli installed? Try: npm install -g @google/gemini-cli`
+			});
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}, 5e3);
+		}, timeoutMs);
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			const isNotFound = err.code === "ENOENT" || err.message.includes("ENOENT");
+			resolve({
+				output: {
+					sessionId: null,
+					response: ""
+				},
+				isError: true,
+				errorMessage: isNotFound ? `gemini binary not found. Install with: npm install -g @google/gemini-cli` : `Failed to spawn gemini: ${err.message}`
+			});
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (timedOut) {
+				resolve({
+					output: {
+						sessionId: null,
+						response: ""
+					},
+					isError: true,
+					errorMessage: `gemini timed out after ${timeoutMs / 1e3}s`
+				});
+				return;
+			}
+			if (code !== 0) {
+				const detail = stderr.trim() || stdout.trim() || `exit code ${code}`;
+				resolve({
+					output: {
+						sessionId: null,
+						response: ""
+					},
+					isError: true,
+					errorMessage: `gemini exited with code ${code}: ${detail}`
+				});
+				return;
+			}
+			resolve({
+				output: parseGeminiOutput(stdout),
+				isError: false
+			});
+		});
+	});
+}
+const server = new McpServer({
+	name: "gemini-cli-mcp",
+	version: "0.1.0"
+});
+server.registerTool("cli", {
+	description: "Send a task or question to Gemini CLI and return the response. Gemini runs headlessly with full tool access (file read/write, web search, shell commands). Use this to delegate tasks that benefit from Gemini's capabilities or to get a second opinion.",
+	inputSchema: {
+		prompt: z.string().describe("The task or question to send to Gemini CLI"),
+		cwd: z.string().describe("Absolute path to the working directory for Gemini to operate in"),
+		model: z.string().optional().describe("Model to use. Omit to use Gemini CLI's default (auto). Official aliases: \"auto\" (default routing), \"pro\" (complex reasoning), \"flash\" (fast, balanced), \"flash-lite\" (fastest). Or pass a concrete model name like \"gemini-2.5-pro\"."),
+		sessionId: z.string().optional().describe("Resume a previous Gemini session by ID. The session ID is returned in the structured output of each call.")
+	},
+	outputSchema: {
+		sessionId: z.string().nullable().describe("Gemini CLI session ID"),
+		response: z.string().describe("Gemini's text response"),
+		models: z.record(z.string(), z.number()).describe("Model name → total tokens used"),
+		tools: z.record(z.string(), z.number()).describe("Tool name → call count")
+	},
+	annotations: {
+		readOnlyHint: false,
+		openWorldHint: true
+	}
+}, async ({ prompt, cwd, model, sessionId }) => {
+	const timeoutMs = 12e4;
+	const result = await runGemini(prompt, cwd, model, timeoutMs, sessionId);
+	if (result.isError) return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: result.errorMessage ?? "Unknown error"
+		}]
+	};
+	const structured = extractStructuredOutput(result.output);
+	return {
+		content: [{
+			type: "text",
+			text: structured.response
+		}],
+		structuredContent: structured
+	};
+});
+const isMain = process.argv[1] !== void 0 && (import.meta.url === `file://${process.argv[1]}` || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("dist/index.js"));
+if (isMain) {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+//#endregion
+export { buildGeminiArgs, extractStructuredOutput, parseGeminiOutput, runGemini };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@danwahl/gemini-cli-mcp",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "MCP server that exposes Gemini CLI as a single tool for Claude Code",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danwahl/gemini-cli-mcp.git"
+  },
+  "keywords": ["mcp", "gemini", "claude", "llm", "ai"],
+  "engines": { "node": ">=18" },
+  "bin": "./cli.js",
+  "scripts": {
+    "build": "tsdown src/index.ts",
+    "test": "node --import tsx/esm --test src/index.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "cli.js"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsdown": "^0.10.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.0"
+  }
+}