aistudio-mcp

Google AI Studio inside Claude. One local MCP server, zero dependencies, covering the whole current Gemini API surface: text and vision, Nano Banana images, Gemini Omni Flash video, Veo 3.1 video with native audio, and Gemini TTS voiceover.

Install

1. Get an API key — https://aistudio.google.com/apikey (free tier works; Veo and 4K images need billing).

2. Put aistudio-mcp.mjs somewhere permanent, e.g. ~/github/aistudio-mcp/.

3. Add it to Claude Desktop. Open ~/Library/Application Support/Claude/claude_desktop_config.json and add the aistudio block (keep any servers already in there):

{
  "mcpServers": {
    "aistudio": {
      "command": "node",
      "args": ["/Users/YOUR_NAME/github/aistudio-mcp/aistudio-mcp.mjs"],
      "env": {
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}

The path must be absolute — ~ is not expanded. Run echo $HOME to get yours.

4. Restart Claude Desktop. The tools appear in Claude, and in Cowork sessions linked to this Mac.

Check it before restarting:

GEMINI_API_KEY=AIza... node ~/github/aistudio-mcp/aistudio-mcp.mjs --selftest

That lists every model your key can reach. --selftest veo filters the list.

Related MCP server: Banana Image MCP

Tools

Generated files are written to ~/Downloads/ai-studio-mcp (override with AISTUDIO_OUTPUT_DIR) and the path comes back in the result. Images are also returned inline so Claude can look at what it made and iterate.

Models

Defaults are current as of September 2026. Google renames and retires model IDs constantly — when a call fails with 404, run list_models and override with env vars.

Other settings: AISTUDIO_OUTPUT_DIR, AISTUDIO_MAX_WAIT_MS (default 240000).

Notes

• Veo is slow. 11 seconds to 6 minutes. If it outlives the tool call you get an operation name back — Claude calls veo_poll with it, nothing is lost.

• Omni vs Veo. Omni Flash is fast and conversationally editable ("now make it night"). Veo is the cinematic one and the only one that generates a real soundtrack. Draft with Omni, finish with Veo.

• Files API references expire after 48 hours.

• Errors are returned, not thrown, with a hint attached — a 404 tells Claude to run list_models, a 403 flags allowlist, a 429 flags quota. Claude can recover on its own.

• No dependencies. Node 18+. Nothing to npm install, nothing to keep updated.

Ad pipeline

The four tools chain, which is the actual point:

gemini_image      → product still, exact aspect ratio
gemini_video      → animate it, iterate the motion conversationally
veo_video         → final cinematic cut with synced audio
gemini_tts        → voiceover track

Tests

npm test

Twelve end-to-end tests, no API key and no network. Each one spawns the real server and speaks JSON-RPC to it over stdio, the same way Claude Desktop does, while GEMINI_API_BASE points the server at a local mock of Google's API. That lets the suite assert on the exact requests that go upstream, not just the replies:

• the key travels in the x-goog-api-key header and never in a URL

• every gemini_generate option lands on the right field (systemInstruction, responseMimeType, …)

• a queued image job is polled to completion, and the input image Google echoes back in the interaction is never mistaken for the output (media is searched narrowest-scope first)

• raw 24 kHz PCM from TTS is wrapped in a byte-correct WAV header

• 404 / 403 / 429 each come back with a hint the model can act on, and a missing key, a bad JSON line or an unknown tool is a reported error rather than a dead server

CI runs the suite on Node 18, 20 and 22.

Design choices

• Zero dependencies. The MCP stdio transport is newline-delimited JSON-RPC 2.0; it takes about forty lines to implement directly. Nothing to install means nothing to break when a transitive package changes.

• Schema-agnostic media extraction. Google's response shapes differ between the Interactions API, generateContent and Veo's long-running operations, and they change. collectMedia walks any JSON tree for payloads rather than hard-coding one path, and pickMedia searches the output scopes first.

• Long jobs never block. A render that outlives the tool call returns its id, and veo_poll / interaction_get resume it later, so a six-minute Veo shot does not time out a conversation.

License

MIT