Skip to main content
Glama
leighsrodney-prog

gemini-mcp-server

by leighsrodney-prog
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
promptYes
systemNo
max_output_tokensNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does valuable work: it documents default model resolution (GEMINI_MODEL or gemini-flash-latest), retry-with-backoff on rate limits/outages, and fallback to GEMINI_FALLBACK_MODELS. It omits auth/API-key requirements and latency or cost implications, so it is strong but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action in one sentence, then appends compact per-parameter notes. Every sentence adds information, though the run-on model sentence could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-format explanation is unnecessary, and the description still notes the text-answer return. It covers defaults and failure behavior, which is the main risk area for an external LLM call; only auth requirements and the token limit remain unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it explains only 2 of 4 parameters (`model` and `system`). `prompt` is self-evident from its name, but `max_output_tokens` (default 2048) is undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb (ask), resource (Google Gemini), and the return type (its text answer). There are no sibling tools to disambiguate against, and the purpose is unambiguous on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (a question-in/text-answer-out operation) and explains fallback behavior, but gives no explicit when-to-use guidance, prerequisites, or exclusions. With no siblings this is acceptable but thin.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev0.1.0
    • First observedgemini_ask
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.9/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool (gemini_ask), there is no possibility of confusing it with another tool. Its purpose—send a prompt to Gemini and return the answer—is unambiguous.

Naming Consistency5/5

The lone name gemini_ask follows a clean snake_case verb_noun pattern and is fully self-consistent. There are no competing conventions to create inconsistency.

Tool Count3/5

A one-tool surface is thin for a server, even though asking Gemini is genuinely the core capability. The rubric treats a single tool as borderline, and there is no supporting surface (e.g. conversation or model listing).

Completeness3/5

The basic one-shot question/answer flow is covered, including model and system-instruction options. However, there is no multi-turn conversation, model discovery, or other lifecycle operations, leaving notable gaps for a general Gemini integration.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Gemini MCP Server

    reouno
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Google Gemini AI models through MCP protocol. Provides text generation capabilities with configurable model selection and temperature settings.
    62 npm
    MIT

  • gemini-mcp

    nhosoya
    A
    license
    Not graded
    quality
    D
    maintenance
    Minimal MCP server that provides access to Google's Gemini API with Google Search grounding for up-to-date information through a single ask_gemini tool.
    MIT

  • llm-fallback-mcp

    KhushalB25
    A
    license
    A
    quality
    D
    maintenance
    MCP server that completes prompts with automatic provider fallback across OpenAI, Anthropic Claude, and Google Gemini. It is rate-limit aware, retries on transient failures, and provides a transparent attempt log.
    2
    10 npm
    MIT