@voidog/mcp-gemini-cli

An MCP server that bridges Claude Code (or any MCP client) to a locally-installed gemini CLI in headless mode. No API keys, no library — it shells out to the gemini binary you already have.

Why

• Get a second opinion from Gemini Pro on a file or design without leaving Claude Code.
• Offload large-context reading to Gemini's long-context Pro model and have Claude consume the digest.
• Optionally delegate agent work (file edits, shell tools) to Gemini in auto_edit / yolo / plan modes — gated behind an explicit user-confirmation flow.

Requirements

• Node.js 20+
• gemini CLI installed and authenticated (gemini auth ... already done)
• v0.40.x of the gemini CLI verified; later 0.x should also work.

Tools

| Tool | Purpose | | --- | --- | | gemini_list_models | List the model aliases this MCP recognises (auto, pro, flash, flash-lite) plus selection guidance. | | gemini_ask | Run gemini in headless mode (-p). Read-only by default. | | gemini_agent | Run gemini with auto-approval (--approval-mode). Requires explicit user_confirmation; yolo further requires GEMINI_MCP_ALLOW_YOLO=true. | | gemini_list_sessions | Wraps gemini --list-sessions for the cwd. | | gemini_delete_session | Wraps gemini --delete-session <index|UUID>. |

gemini_ask parameters

• prompt (string, required)
• model (string, optional — defaults to env or auto)
• output_format (text / json / stream-json, default text)
• files (string[]) — appended to the prompt as @<absolute-path>. Files must exist.
• resume (string) — latest, an index number, or a full session UUID (sessions are scoped to working_directory)
• include_directories (string[]), working_directory (string)
• sandbox (boolean), skip_trust (boolean)
• allowed_mcp_server_names (string[]) — what MCP servers gemini itself may use
• extensions (string[]) — -e subset
• timeout_seconds (number, default 180, max 600)

The tool always returns session_id in structuredContent, regardless of output_format, so callers can chain follow-up calls via resume.

gemini_agent extra parameters

• approval_mode (auto_edit | yolo | plan, required)
• user_confirmation (string, required) — a one-line summary of what the user pre-approved.

yolo is gated by env GEMINI_MCP_ALLOW_YOLO=true. The bundled plugin exposes this as a userConfig.allow_yolo toggle.

Environment variables

| Variable | Default | Purpose | | --- | --- | --- | | GEMINI_MCP_ALLOW_YOLO | false | Permit gemini_agent with approval_mode: "yolo". | | GEMINI_MCP_DEFAULT_MODEL | auto | Used when the caller does not pass model. | | GEMINI_MCP_DEFAULT_TIMEOUT_SECONDS | 180 | Used when the caller does not pass timeout_seconds. | | GEMINI_MCP_BIN | gemini | Path/name of the gemini binary. |

Local install

# From this package
npm install
npm run build
node dist/index.js          # acts as a stdio MCP server

# Or in your project's .mcp.json
{
  "mcpServers": {
    "gemini-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@voidog/[email protected]"]
    }
  }
}

Model selection

The MCP recognises four aliases (resolved by gemini itself):

• auto — default. Lets gemini route by task.
• pro — complex reasoning, code review, deliberate analysis.
• flash — simple work or when speed matters more than peak accuracy.
• flash-lite — only when the work is mechanical and any model would produce the same answer.

If the user names a specific model (alias or fully-qualified name), pass it through verbatim.

Security notes

• The MCP shells out via spawn() with an argument array — no shell metacharacter expansion.
• File paths in files are validated with fs.statSync before being passed.
• gemini_agent with yolo is off by default and requires both an explicit user_confirmation string and the GEMINI_MCP_ALLOW_YOLO environment variable.
• Content read via @file flows into Gemini's reasoning. Treat the same way as any LLM input — beware of prompt injection from untrusted files.

License

MIT