Skip to main content
Glama

gemini-mcp-server

CI

A tiny Model Context Protocol stdio server that gives any MCP client one tool, gemini_ask, which sends a prompt to Google Gemini and returns the text answer. It retries with backoff on rate limits and outages, and falls back to another model when one fails.

Why a tiny MCP server?

  • A second opinion inside your agent. Let one assistant consult another model for cross-checks, reviews or drafts without leaving the workflow.

  • Small surface, easy to audit. One tool and about 150 lines of logic. The key comes from env, nothing else is exposed, and you can read all of it in a few minutes.

  • A good MCP learning project. Stdio transport, a typed tool signature and clean error strings are the core of most MCP integrations.

Related MCP server: Gemini MCP

Setup (uv)

git clone <this-repo-url> gemini-mcp-server
cd gemini-mcp-server
uv sync                      # creates .venv and installs mcp (+ pytest in the dev group)
read -rs GEMINI_API_KEY && export GEMINI_API_KEY   # from Google AI Studio
uv run gemini-mcp-server     # speaks MCP over stdio; normally your client launches it
uv run pytest -q             # all HTTP is mocked

Configuration (environment variables)

Variable

Purpose

Default

GEMINI_API_KEY

API key (preferred)

none

GEMINI_API_KEY_FILE

Path to a file holding the key, used only if GEMINI_API_KEY is unset

none

GEMINI_MODEL

Primary model

gemini-flash-latest

GEMINI_FALLBACK_MODELS

Comma-separated fallbacks (empty = none)

gemini-flash-lite-latest

GEMINI_RETRIES

Retries per model on 429/500/503/network errors

3

Error handling: 429/500/503 and network errors are retried with exponential backoff and jitter, and a Retry-After header is honored. Once retries run out, or on a 404 (unknown model), the next model in the chain is tried. 400/401/403 (bad request or bad key) fail fast, because a fallback wouldn't help. Errors come back to the client as a readable Gemini error: ... string instead of a crash. If a fallback model answers, its reply is prefixed with [answered by <model>].

Add it to an MCP client

Most clients (Claude Desktop, Cursor and others) accept a JSON entry like this:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["--directory", "/path/to/gemini-mcp-server", "run", "gemini-mcp-server"],
      "env": { "GEMINI_API_KEY_FILE": "/path/outside/the/repo/gemini.key" }
    }
  }
}

It's better to point GEMINI_API_KEY_FILE at a file with chmod 600 permissions than to paste the key into client config. Restart the client and the gemini_ask tool will appear.

Free-tier caveats

  • The Gemini API free tier has low per-minute and per-day request limits that vary by model and change over time, so expect 429s under load. That's why the retry and fallback logic exists.

  • Free-tier prompts and responses may be used by Google to improve its products. Don't send confidential or personal data.

  • *-latest aliases can change underneath you. Pin a specific model version if you need reproducibility.

  • Availability, quotas and terms are set by Google. Check the current Gemini API pricing and terms pages before relying on it.

Roadmap

  • Streaming responses (streamGenerateContent)

  • Token-usage and latency reporting in tool output

  • Optional per-process rate limiter to stay under free-tier quotas proactively

  • Multi-turn context and file/image inputs

  • Structured (JSON-schema) output mode

How this was built

Built with AI coding assistance as part of my AI-agent operations work. I defined the requirements and error-handling behavior, ran the tests, and reviewed the changes.

License

MIT. See LICENSE.

Available Tools

1 tool
gemini_askA

Ask Google Gemini a question and return its text answer.

model: optional model name (default from GEMINI_MODEL or gemini-flash-latest); on rate limits or outages the server retries with backoff, then falls back to GEMINI_FALLBACK_MODELS. system: optional system instruction.

Inputs: prompt (required), model, system, max_output_tokens. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool exposed, there is no possibility of an agent confusing it with another operation. The tool's purpose (forward a question to Gemini and return text) is stated explicitly and clearly.

    Naming Consistency4/5

    The single name `gemini_ask` uses a clean snake_case verb_noun form with a server prefix, which is readable and idiomatic. There is no second tool to confirm a pattern, so consistency is trivially satisfied rather than demonstrated.

    Tool Count3/5

    A single tool is defensible for a narrowly-scoped 'ask Gemini' wrapper, but it is very thin — anything beyond one-shot prompting (chat, model listing, token counting) requires no tool at all. One tool sits at the borderline of feeling under-scoped.

    Completeness3/5

    For the literal purpose of asking a question, the surface is complete and even handles retries/fallback models. However, the broader domain (multi-turn conversations, listing available models, streaming or structured output) has no coverage, leaving agents with a single dead-end operation.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers