Gemini Cli Mcp

gemini-cli-mcp

> ## ⚠️ Deprecated — no longer maintained > > Google is transitioning Gemini CLI to Antigravity CLI. > On June 18, 2026, Gemini CLI stops serving requests for the free, Google AI > Pro, and Ultra tiers — the exact tiers this project was built to wrap. (Access > continues for paid Gemini API keys and Gemini Code Assist Standard/Enterprise.) > > What this means: > - Free / Pro / Ultra users: this tool stops working after 2026-06-18. Google's > successor is Antigravity CLI. > Note this wrapper targets the gemini binary and does not drive Antigravity's agy. > - Paid API key / Code Assist Standard or Enterprise users: the underlying gemini > CLI keeps working, so this wrapper may keep functioning — but it receives no further updates. > - The code stays available under MIT; the npm package is deprecated (existing installs > keep working). No new features, fixes, or security updates are planned. > > Original documentation is preserved below.

[](https://www.npmjs.com/package/@guibarscevicius/gemini-cli-mcp) [](https://github.com/guibarscevicius/gemini-cli-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://unmaintained.tech/)

Use Gemini's free tier as an on-demand code reviewer from inside Claude Code, Codex, or any MCP-compatible host. gemini-cli-mcp wraps the official @google/gemini-cli and exposes it through the Model Context Protocol — so you can ask Gemini to second-opinion a diff, pair-review a refactor, or scan a long file without leaving your primary agent.

Stateful multi-turn sessions, async jobs, response streaming, and a warm process pool keep latency low enough to be worth using.

Why I built this

I use Claude Code and Codex daily for real work, and I have free Gemini access through my employer. Gemini is genuinely good at long-context reading and at noticing things a different model would miss — but switching tabs to ask it costs flow.

So I made it a tool call. Now my primary agent can hand Gemini a diff, a directory, or a question and keep going. It's not a replacement for either model — it's a cheap second opinion, on demand, in the same loop.

The interesting engineering is the boring stuff: warm process pools so the 12-second cold start doesn't stall the agent, SQLite-backed sessions so multi-turn actually works, and a workspace-scoped @file expander so you can hand Gemini a whole subdirectory in one prompt.

Architecture

flowchart LR
    A[Claude Code / Codexor any MCP host] -->|MCP tool call| B[gemini-cli-mcp]
    B |read/write turns| D[(SQLitesession store)]
    B -->|acquire worker| C[Warm process pool]
    C -.-|manages| E[gemini CLI subprocess]
    B |stream-json over stdio| E
    E -->|HTTPS| F[Google Gemini API]

The MCP server keeps a small pool of pre-spawned gemini CLI processes hot, so a request typically completes in ~4–5 s instead of ~17 s — eliminating the ~12 s cold-start overhead. Multi-turn history is stored in SQLite (node:sqlite, no native deps) and replayed as structured context on every gemini-reply.

Quick Setup (recommended)

npm install -g @guibarscevicius/gemini-cli-mcp
gemini-cli-mcp --setup

The wizard will:

1. Find or install @google/gemini-cli
2. Verify your Gemini authentication
3. Print a ready-to-paste MCP config with absolute paths

Security

| Property | Implementation | |----------|----------------| | No shell injection | spawn() (via spawnInGroup) passes args as an array directly to execve — no shell is invoked | | No arg concatenation | Args array is built programmatically; user input is always a single element | | Env isolation | Subprocess inherits only HOME and PATH | | Structured output | --output-format stream-json produces reliable streaming NDJSON |

Prerequisites

• Node.js ≥ 24 — nodejs.org/en/download
• Gemini CLI installed and authenticated:

npm install -g @google/gemini-cli
gemini  # follow the auth flow (Google subscription — no billing required)

Verify it works:

gemini --prompt "hello" --output-format stream-json

Installation

npx (recommended)

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@guibarscevicius/gemini-cli-mcp"]
    }
  }
}

Add to ~/.claude/settings.json for Claude Code CLI, or your host's MCP config file.

Local development

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-cli-mcp/dist/index.js"]
    }
  }
}

> Model compatibility (Gemini CLI ≥ 0.31): The CLI forces include_thoughts for models that support thinking. Recommended models: gemini-3-flash-preview (fast, default), gemini-3-pro-preview (deep reasoning), and gemini-2.5-flash-lite (lowest-cost throughput). gemini-3.1-pro-preview may appear for eligible users as a rolling preview upgrade.

Tools

ask-gemini — start a new session

Input:
  prompt        string   Required. The message to send.
  model         string   Optional. E.g. "gemini-3-flash-preview". Defaults to CLI default.
  cwd           string   Optional. Working directory — required for any @file path.
  wait          boolean  Optional. Block until done and return response inline (default: false).
  waitTimeoutMs number   Optional. Max ms to wait when wait=true (default: 90000).
  expandRefs    boolean  Optional. Set to false to disable @file expansion (e.g. Vue @click syntax). Default: true.

Output (async — default):
  jobId          string   Poll with gemini-poll or cancel with gemini-cancel.
  sessionId      string   Use with gemini-reply for multi-turn conversations.
  pollIntervalMs number   Suggested polling interval in ms (2000).

Output (wait: true — done):
  jobId          string
  sessionId      string
  response       string   Gemini's complete response.
  pollIntervalMs number

Output (wait: true — timeout):
  jobId           string
  sessionId       string
  partialResponse string   Partial output collected before timeout (may be empty).
  timedOut        true
  pollIntervalMs  number

gemini-reply — continue an existing session

Input:
  sessionId     string   Required. Returned by ask-gemini.
  prompt        string   Required. Follow-up message.
  model         string   Optional. Override the model for this turn.
  cwd           string   Optional. Working directory for relative @file paths.
  wait          boolean  Optional. Block until done (default: false).
  waitTimeoutMs number   Optional. Max ms to wait when wait=true (default: 90000).
  expandRefs    boolean  Optional. Set to false to disable @file expansion. Default: true.

Output:
  jobId              string
  pollIntervalMs     number
  response           string   (wait: true — done)
  partialResponse    string   (wait: true — timeout)
  timedOut           true     (wait: true — timeout)
  historyTruncated   boolean  Present and true when older turns were dropped due to GEMINI_MAX_HISTORY_TURNS.
  historyTurnCount   number   Total turns in the session at the time of this reply (present when historyTruncated is true).

Sessions auto-expire after 60 minutes of inactivity.

gemini-poll — check job status

Input:
  jobId   string   Required. From ask-gemini or gemini-reply output.

Output (pending):
  jobId           string
  status          "pending"
  partialResponse string   Partial output accumulated so far.

Output (done):
  jobId    string
  status   "done"
  response string   Gemini's complete response.

Output (error):
  jobId   string
  status  "error"
  error   string

Output (cancelled):
  jobId   string
  status  "cancelled"
  error   string   Optional cancellation detail.

gemini-cancel — cancel a pending job

Input:
  jobId   string   Required.

Output:
  jobId       string
  cancelled   boolean   true if the running subprocess was killed.
  alreadyDone boolean   true if the job had already completed before cancel arrived.

gemini-health — server health and diagnostics

Input:
  (none)

Output:
  binary.path         string | null   Absolute path to the gemini binary (null if only "gemini" on PATH).
  env                 object          Active env overrides (GEMINI_MAX_CONCURRENT, etc.). Empty if all defaults.
  pool.enabled        boolean         Whether the warm process pool is active.
  pool.ready          number          Processes currently ready in the pool.
  pool.size           number          Configured pool size.
  pool.lastError      string | null   Last spawn error message (null when healthy).
  pool.consecutiveFailures number     Consecutive spawn failures since last success.
  concurrency.max     number          GEMINI_MAX_CONCURRENT value.
  concurrency.active  number          Currently running Gemini subprocesses.
  concurrency.queued  number          Requests waiting for a concurrency slot.
  jobs.active         number          Jobs currently in "pending" state.
  jobs.total          number          Total jobs tracked (all statuses).
  jobs.byStatus       object          Counts by status: { pending, done, error, cancelled }.
  sessions.total      number          Total sessions in the store.
  server.uptime       number          Process uptime in seconds.
  server.version      string          Package version.
  cli.version            string | null   Detected CLI version (e.g. "0.34.0").
  cli.minSupported       string          Minimum supported version ("0.30.0").
  cli.versionOk          boolean         Whether the detected version meets the minimum.
  cli.detectedFlags      number          Number of flags found in --help output.
  cli.activeAdaptations  array           Flag adaptations in effect (e.g. "--approval-mode yolo (replaces --yolo)").
  cli.detectionError     string | null   Error message if detection failed.

gemini-sessions — list or export sessions

The discriminator is the presence of sessionId: omit it to list active sessions; provide it to export that session's full conversation history.

Input:
  sessionId   string   Optional. When omitted, returns the list of active sessions.
                       When provided, returns the full conversation history of that session.
  format      string   Optional. "json" (default) or "markdown". Only used with sessionId.
  lastN       number   Optional. Export only the last N turns. Only used with sessionId.

Output (no sessionId — list path):
  sessions   array    Array of session objects, sorted by most recently accessed.
    id             string   Session ID (pass back as sessionId to export this session).
    lastAccessed   number   Unix-ms timestamp of the last turn.
    turnCount      number   Number of turns stored in the session.
    expiresAt      number   Unix-ms timestamp when the session will expire (60 min after lastAccessed).
  total      number   Total number of sessions.

Output (with sessionId — export path):
  sessionId       string   The exported session ID.
  turnCount       number   Number of turns included in the export.
  totalTurnCount  number   Total turns in the session (present only when lastN is used).
  format          string   The format used ("json" or "markdown").
  turns           array    Array of { role, content } objects.
  content         string   Pre-rendered representation in the requested format
                           (JSON.stringify of turns, or bold-label markdown paragraphs).
  exportedAt      string   ISO 8601 timestamp of the export.

gemini-batch — parallel prompt processing

Input:
  prompts      array    Required. Array of prompt strings to process in parallel.
  model        string   Optional. Model to use for all prompts.
  cwd          string   Optional. Working directory for @file references.
  expandRefs   boolean  Optional. Set to false to disable @file expansion. Default: true.
  wait         boolean  Optional. Block until all jobs complete (default: true).

Output (wait: true — default):
  results   array    Array of result objects, one per prompt (in order):
    index     number    Position in the input prompts array.
    status    string    "done" or "error".
    response  string    Gemini's response (present when status is "done").
    error     string    Error message (present when status is "error").
  summary   object   { total, succeeded, failed, durationMs } counts and elapsed time.

Output (wait: false):
  jobs           array    Array of { jobId, index } objects — one per prompt.
  pollIntervalMs number   Suggested polling interval in ms (2000).

gemini-research — deep research with grounding

Uses Gemini's built-in research capabilities for queries requiring up-to-date information or multi-source synthesis.

Input:
  query         string   Required. The research question or topic.
  depth         string   Optional. "quick", "standard" (default), or "deep".
  model         string   Optional. Defaults to CLI default.
  cwd           string   Optional. Working directory for @file references.
  expandRefs    boolean  Optional. Set to false to disable @file expansion. Default: true.
  wait          boolean  Optional. Block until done (default: true).
  waitTimeoutMs number   Optional. Max ms to wait when wait=true (default: 90000 for quick/standard, 180000 for deep).

Output (wait: true — done, default):
  jobId          string
  response       string   Gemini's complete research response.
  pollIntervalMs number

Output (wait: true — timeout):
  jobId           string
  partialResponse string   Partial output collected before timeout (may be empty).
  timedOut        true
  pollIntervalMs  number

Output (wait: false — async):
  jobId          string   Poll with gemini-poll or cancel with gemini-cancel.
  pollIntervalMs number   Suggested polling interval in ms (2000).

Resources

Read-only data exposed via the MCP Resources API (no tool call required — hosts can cache by URI).

gemini://models — available Gemini models

Returns the curated list of Gemini models with tier (fast / balanced / deep), description, and notes. Honors the GEMINI_MODELS env var (comma-separated IDs) as an override; when set, returned models have source: "custom" and tier: "balanced".

Output:
  models  array of { id, description, tier, notes }
  total   number
  source  "curated" | "custom"

gemini://server/health, gemini://sessions, gemini://jobs

Runtime diagnostics, active session list, and pending job list respectively. Templates gemini://sessions/{sessionId} and gemini://jobs/{jobId} return detail for a specific session or job.

Async workflow

ask-gemini returns immediately with a jobId. Use gemini-poll to check status:

// Start a long request without blocking
const { jobId, sessionId } = await ask_gemini({
  prompt: "Summarize this large codebase: @src/**/*.ts",
  cwd: "/path/to/your/project"
})

// Poll until done (typically 4–20 s)
let result
do {
  await new Promise(r => setTimeout(r, 2000))
  result = await gemini_poll({ jobId })
} while (result.status === "pending")

// Continue the conversation
const { jobId: j2 } = await gemini_reply({
  sessionId,
  prompt: "What are the 3 most important findings?"
})

For simple one-shot requests, use wait: true:

const { response } = await ask_gemini({
  prompt: "What is the capital of France?",
  wait: true
})

Using @file syntax

The server supports @file references to inject file contents directly into the prompt.

> Always pass cwd — the server enforces a workspace boundary at cwd. Any @file path that resolves outside the tree is rejected with Path not in workspace.

Single file:

ask_gemini({ prompt: "Review this file: @src/auth.ts", cwd: "/path/t

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [guibarscevicius](https://github.com/guibarscevicius)
- **Source:** [guibarscevicius/gemini-cli-mcp](https://github.com/guibarscevicius/gemini-cli-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.