# aistudio-mcp

[![test](https://github.com/shubhankar360/aistudio-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/shubhankar360/aistudio-mcp/actions/workflows/test.yml)

A local MCP server that lets Claude call Google's Gemini models as tools: text and vision, Nano Banana
images, Gemini Omni Flash video, Veo 3.1 video with native audio, and Gemini TTS voiceover. It's one
Node file with no dependencies.

The idea came from my work at Solquara, where one ad passes through several models in a row (a still,
then motion, then a soundtrack and voiceover). I wanted to plan that in a Claude conversation and let
Claude run each step, instead of copying prompts between browser tabs.

## Install

**1. Get an API key** at 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):

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

The path must be absolute, because `~` isn't 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:**

```bash
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.

## Tools

| Tool | What it does |
|---|---|
| `gemini_generate` | Text, vision, PDF, audio and video reasoning. Attach local files; big ones auto-upload. |
| `gemini_image` | Nano Banana generate and edit. Input images for edits, compositing, character consistency. |
| `gemini_video` | Omni Flash: text-to-video, image-to-video, first/last frame interpolation, extension, and multi-turn conversational editing. |
| `veo_video` | Veo 3.1 cinematic video **with native synced audio**. First/last frame, up to 3 reference images. |
| `veo_poll` | Picks up a Veo render that outlived the tool call. |
| `gemini_tts` | Voiceover. 30 voices, single or multi-speaker, directable ("Say warmly and slowly: ..."). |
| `upload_file` | Files API upload for big video/audio/PDF; returns a reusable `files/...` reference (48h). |
| `interaction_get` | Retrieves a queued image/video job by id. |
| `list_models` | What your key can actually reach right now. |

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 often, so when a call
fails with 404, run `list_models` and override with env vars.

| Env var | Default | Notes |
|---|---|---|
| `GEMINI_MODEL` | `gemini-3.8-flash` | `gemini-3.1-pro-preview` for harder reasoning |
| `GEMINI_IMAGE_MODEL` | `gemini-3.1-flash-image` | `gemini-3-pro-image` (Nano Banana Pro) for best quality; `-lite` is 1K only |
| `GEMINI_VIDEO_MODEL` | `gemini-omni-1.1-flash` | may need allowlist access on some keys |
| `GEMINI_VEO_MODEL` | `veo-3.1-generate-preview` | `veo-3.1-lite-generate-preview` for cheap drafts |
| `GEMINI_TTS_MODEL` | `gemini-3.1-flash-tts-preview` | |

Other settings: `AISTUDIO_OUTPUT_DIR`, `AISTUDIO_MAX_WAIT_MS` (default 240000).

## Notes

- **Veo is slow:** anywhere from 11 seconds to 6 minutes. If it outlives the tool call you get an operation
  name back, Claude calls `veo_poll` with it, and 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 points at the allowlist and a 429 at quota, so Claude can usually recover on its own.
- **No dependencies.** Node 18+. Nothing to `npm install`, nothing to keep updated.

## Ad pipeline

This is the chain I built it for:

```
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

```bash
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 and 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 reported as an error instead of killing the 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, and 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