aio-gemini-mcp
Give your AI agent ears, a voice, eyes, and a studio. One MCP server for Gemini's image, video, speech, transcription, and music models.
What is this?
Most coding agents only read and write text. This server plugs them into Google's Gemini media models so they can also hear audio, speak, see and make images, compose music, and produce video, all as ordinary MCP tool calls.
| Give your agent... | With | Example |
|---|---|---|
| Ears | transcribe_audio |
Turn a meeting recording into a diarized transcript with word timestamps |
| A voice | generate_speech |
Read a changelog aloud, or script a two-speaker dialogue |
| Eyes and a canvas | generate_image |
Create or edit images, grounded in Google Search and Image Search |
| A composer | generate_music |
Write an instrumental, a song with lyrics, or music inspired by an image |
| A camera | generate_omni |
Generate, edit, and extend video, including first/last-frame interpolation |
It is a stdio FastMCP server built on the Google Gen AI SDK and the Interactions API. It starts no HTTP server and opens no port. Stdout carries MCP messages only, and diagnostics go to stderr.
Quick Start
You need uv and a
Gemini API key. Add the server to your MCP
client's mcpServers configuration (also in
mcp-config.example.json). uvx fetches the latest
release from PyPI:
{
"mcpServers": {
"gemini": {
"command": "uvx",
"args": ["aio-gemini-mcp@latest"],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
}
}
}
| Variable | Purpose |
|---|---|
GEMINI_API_KEY |
Gemini Developer API key. Takes precedence over GOOGLE_API_KEY. |
GOOGLE_API_KEY |
Fallback key. |
GEMINI_OUTPUT_DIR |
Absolute directory for saved media. Defaults to generated-media/ in the server's working directory. |
.env files are not loaded. A missing key does not stop startup or tool
discovery, only the tools that call Google. Prompts are sent to Google, and API
use may incur charges.
Tools
| Tool | Purpose |
|---|---|
generate_image |
Nano Banana image generation and editing, with optional Google Search and Image Search grounding |
generate_omni |
Omni video generation, editing, extension, and first/last-frame interpolation |
transcribe_audio |
Speech recognition with smart/verbatim modes, diarization, and word timestamps |
generate_speech |
Single- or two-speaker TTS with voice, language, and delivery style controls |
generate_music |
Lyria songs, instrumental music, short clips, lyrics, and image-inspired music |
get_prompt_guide |
Google's official prompting guide for image, video, speech, music, or transcription |
get_interaction / cancel_interaction / delete_interaction |
Poll, cancel, or delete stored Google interactions |
upload_file / get_file / list_files / delete_file / download_file |
Manage Google Files for large inputs and generated outputs |
See docs/tools.md for every argument, default, constraint, and return shape.
Examples
Tool arguments are JSON for your MCP client, not terminal commands.
Generate an image
{
"prompt": "Create a cinematic watercolor landscape",
"aspect_ratio": "16:9",
"image_size": "2K"
}
Set "image_search": true when the image must depict a real subject accurately, such as a species or landmark. To edit a local image, add "media": [{"type": "image", "mime_type": "image/png", "path": "/ABSOLUTE/image.png"}].
Transcribe audio
{
"audio": {"type": "audio", "mime_type": "audio/mp3", "path": "/ABSOLUTE/audio.mp3"},
"language_codes": ["en-US"],
"diarization": true,
"word_timestamps": true
}
Speak with two voices
{
"turns": [
{"text": "Hello!", "speaker": "Joe", "style": "cheerful"},
{"text": "Hi Joe.", "speaker": "Jane", "style": "relaxed"}
],
"speakers": [
{"speaker": "Joe", "voice": "Puck"},
{"speaker": "Jane", "voice": "Kore"}
]
}
Compose music
{
"prompt": "A two-minute instrumental jazz track in D minor, with piano, upright bass, and brushed drums",
"mime_type": "audio/mp3"
}
Generate video in the background
{
"prompt": "A slow tracking shot of waves at sunset, with ocean sounds",
"aspect_ratio": "16:9",
"resolution": "1080p",
"duration_seconds": 8,
"background": true
}
Use the returned id with get_interaction until the status is terminal. The server never auto-polls or auto-retries, so a retry cannot create a duplicate charge.
How it behaves
- Inputs. Each
mediaitem takes exactly one of an absolutepath, base64data, or a Google Filesuri. Local and base64 input is capped at 10 MiB per request. For larger files, useupload_file, thenget_fileuntil the state isACTIVE. - Outputs. Binary results are saved with unique, private (
0600) file names and never overwrite existing files. The result lists the absolutepath. Base64 is omitted unless you setinclude_inline_data: true. - Continuation. Every call is stored with Google. Pass a returned
idasprevious_interaction_idto continue or edit. Options such as voices and output format apply per call and must be repeated. - Honest status.
completed,blocked,incomplete,failed, andcancelledare returned as Google reports them, even when the output is empty. - Timeouts. Metadata requests time out after 60 seconds. Media creation, upload, and download default to 600 seconds and accept
timeout_secondsfrom 1 to 1800. - Errors. Upstream error details are redacted from tool errors.
Prompting guides
get_prompt_guide is read-only, offline, and free. It needs no API key and sends
nothing to Google. It returns Google's own wording, templates, and examples (not
AI-written summaries) with sources, the retrieval date, and notes on how the advice
maps to these tools. Call it before building a media request.
{"guide": "music"}
The guides are a bundled snapshot dated 2026-10-18, not a live lookup. See
docs/prompt-guides.md for sources, attribution, and
refresh steps.
Models
Model IDs were verified on 2026-10-18 against Google's model catalog. Tool schemas list the supported choices but cannot report what your account can access. There is no legacy fallback.
| Capability | Default | Other choices |
|---|---|---|
| Images | gemini-nano-banana-2.1 |
gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-3-pro-image |
| Video | gemini-omni-1.1-flash |
None |
| Transcription | gemini-3.5-transcribe |
None |
| Speech | gemini-3.8-flash-tts |
gemini-3.8-flash-lite-tts |
| Music | lyria-3.5 |
lyria-3-clip-preview |
Every generation call uses client.aio.interactions.create. Live audio,
Lyria RealTime, and voice design or cloning use separate APIs and are out of scope.
See docs/media-api.md for sources and per-model constraints.
Project Structure
docs/
media-api.md
prompt-guides.md
tools.md
src/
aio_gemini/
data/guides/
__init__.py
__main__.py
catalog.py
guides.py
media.py
server.py
tests/
mcp-config.example.json
pyproject.toml
uv.lock
Documentation
| Resource | Description |
|---|---|
docs/tools.md |
Arguments, defaults, accepted values, and return shapes for every tool |
docs/media-api.md |
Model catalog sources and API boundaries |
docs/prompt-guides.md |
Guide sources, attribution, and how to refresh them |
Development
uv sync --frozen
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build
Tests mock Google requests, check the real SDK's Interactions HTTP transport, and run real stdio subprocesses against current and legacy MCP clients. They need no credentials and make no Google API calls. Live generation needs your own API key and is not covered.
To run a local checkout instead of the published package:
uv --directory /path/to/gemini-mcp run --frozen aio-gemini-mcp
The server waits for MCP messages on stdin, so launch it from an MCP client rather than a terminal.
Metadata
Release files for aio-gemini-mcp 0.5.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aio_gemini_mcp-0.5.3.tar.gz | 36.7 kB | Without provenance | Details for aio_gemini_mcp-0.5.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aio_gemini_mcp-0.5.3-py3-none-any.whl | Python 3 | none | any | Details for aio_gemini_mcp-0.5.3-py3-none-any.whl |
Total release size: 78.5 kB
Release files / aio_gemini_mcp-0.5.3.tar.gz
| Download URL | aio_gemini_mcp-0.5.3.tar.gz |
|---|---|
| Size | 36.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5fd410e8b1538e5a842358252054f7f2aa7fc48599ddba87fe00e8c462a50bdc
|
|
BLAKE2b-256 checksum How to use checksums |
d776789cc81a6337e10fe4cf7fa606fa37bc57f19063cbca9863b22109f09caa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aio_gemini_mcp-0.5.3-py3-none-any.whl
| Download URL | aio_gemini_mcp-0.5.3-py3-none-any.whl |
|---|---|
| Size | 41.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a49a81da81f8f1a407bfd8eee255757678a791d5191d2cd6de0d547da5c18e2
|
|
BLAKE2b-256 checksum How to use checksums |
947acf93bff2335689bb2bfdb4f741b592d7830096b7da4a2a621e2170da75dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for aio-gemini-mcp 0.5.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.