Skip to main content
A coding agent connected through the Gemini sparkle to hearing, voice, images, music, and video

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.

Google Gemini PyPI Downloads Build

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 media item takes exactly one of an absolute path, base64 data, or a Google Files uri. Local and base64 input is capped at 10 MiB per request. For larger files, use upload_file, then get_file until the state is ACTIVE.
  • Outputs. Binary results are saved with unique, private (0600) file names and never overwrite existing files. The result lists the absolute path. Base64 is omitted unless you set include_inline_data: true.
  • Continuation. Every call is stored with Google. Pass a returned id as previous_interaction_id to continue or edit. Options such as voices and output format apply per call and must be repeated.
  • Honest status. completed, blocked, incomplete, failed, and cancelled are 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_seconds from 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.


Star History Chart

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)

Source distribution for aio-gemini-mcp 0.5.3
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)

Table of built distributions (wheels) for aio-gemini-mcp 0.5.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page