# 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)

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):

```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 — `~` 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:**

```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 constantly — 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.** 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

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