gemini-mcp-server
Allows MCP clients to send prompts to Google Gemini models via the Gemini API and receive text answers, with configurable primary/fallback models and retry handling for rate limits and outages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-mcp-server ask Gemini to review this Python function for bugs and suggest fixes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project's home is now github.com/globe-teck/gemini-mcp-server. This copy stays up for existing links. Please open issues and pull requests there.
gemini-mcp-server
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 mockedConfiguration (environment variables)
Variable | Purpose | Default |
| API key (preferred) | none |
| Path to a file holding the key, used only if | none |
| Primary model |
|
| Comma-separated fallbacks (empty = none) |
|
| Retries per model on 429/500/503/network errors |
|
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.
*-latestaliases 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 toolgemini_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
Scored across 1 tool
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.
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.
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).
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
Related MCP Connectors
Remote MCP for Gemini upgrade evals, prompt regressions, output diffs, and eval receipts.
Account-less MCP access to 45 Gemini models & autonomous agents via L402, x402, and MPP.
Proxy Gemini (Vertex AI) completions wrapped in OpenTelemetry trace spans; returns the answer plus t
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Google Gemini AI models through MCP protocol. Provides text generation capabilities with configurable model selection and temperature settings.285 npmMIT
- AlicenseNot gradedqualityDmaintenanceMinimal 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
- AlicenseNot gradedqualityBmaintenanceConnects MCP clients to Gemini Cloud Assist APIs, enabling users to understand, manage, and troubleshoot their Google Cloud environment using natural language.72Apache 2.0
- AlicenseAqualityCmaintenanceExposes a single chat tool that lets any MCP client send text prompts together with images, PDFs, or Office attachments to a self-hosted Gemini web endpoint and get OpenAI-compatible responses back. An optional companion checker keeps the underlying Google session cookies fresh automatically so requests keep working without manual re-authentication.1MIT