Metadata-Version: 2.5
Name: turbogen-mcp
Version: 0.1.1
Summary: MCP server for Turbogen: Seedance, Kling, Veo, Nano Banana Pro and more - images, video and audio, pay-as-you-go
Project-URL: Homepage, https://turbogen.app
Project-URL: Documentation, https://turbogen.app/api-docs#mcp
Project-URL: Pricing, https://turbogen.app/pricing
Author-email: Turbogen <hello@turbogen.app>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-image,ai-video,claude,kling,mcp,model-context-protocol,nano-banana,seedance,veo
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

# Turbogen MCP server

<!-- mcp-name: app.turbogen/turbogen -->

Generate images, video and audio with Turbogen straight from Claude Desktop, Claude Code, Cursor or any
other MCP client. Same models and prices as the studio; credits come from your balance.

## Tools

| Tool | What it does |
|---|---|
| `list_models(kind?)` | Model ids, aspect/voice choices, options and credit prices (`kind` = image, video or audio) |
| `generate_image(prompt, model="nano-banana-2", aspect="1:1", option?, reference_images?)` | Image, saved locally; a preview is returned when the file is under 1 MB |
| `generate_video(prompt, model="veo-3.1-fast", aspect="16:9", option="8s", image_path?)` | Video clip; pass `image_path` for image-to-video |
| `generate_audio(text_or_prompt, model="voice", aspect?, option?, lyrics?)` | `voice` (aspect = voice name), `music` (aspect = Instrumental / With vocals + lyrics) or `sfx` |
| `upscale_image(path, scale="2x")` | Upscale a local image 2x or 4x |
| `get_balance()` | Remaining credits |
| `job_status(job_id, download=false)` | Status of a job, e.g. one that took longer than the 10-minute wait |

Generation tools submit the job, poll every 3 s for up to 10 minutes, download the result into the output
folder and return the local path, the cost and your remaining credits.

## Get an API key

API access comes with the Boost, Turbo and Max packs. Open **API** in the studio
(`https://turbogen.app/#/apikeys`), create a key and copy it (`lk_...`, shown only once).

## Configuration

| Variable | Required | Default |
|---|---|---|
| `TURBOGEN_API_KEY` | yes | — |
| `TURBOGEN_BASE_URL` | no | `https://turbogen.app` |
| `TURBOGEN_OUTPUT_DIR` | no | `~/Downloads/turbogen` |

## Install

With [uv](https://docs.astral.sh/uv/) nothing needs installing up front, `uvx` runs it on demand:

```bash
uvx turbogen-mcp
```

Or install the command once with pipx (or uv tool):

```bash
pipx install turbogen-mcp      # or: uv tool install turbogen-mcp
turbogen-mcp                            # waits for an MCP client on stdin; Ctrl+C to quit
```

Plain venv:

```bash
python -m venv .venv
.venv/bin/pip install turbogen-mcp     # Windows: .venv\Scripts\pip install turbogen-mcp
```

Requires Python 3.10+.

## Claude Desktop

Edit `claude_desktop_config.json` (Settings > Developer > Edit Config; macOS:
`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and restart Claude Desktop:

```json
{
  "mcpServers": {
    "turbogen": {
      "command": "uvx",
      "args": ["turbogen-mcp"],
      "env": {
        "TURBOGEN_API_KEY": "lk_your_key_here"
      }
    }
  }
}
```

With pipx use `"command": "turbogen-mcp"` and drop `args`. If the app cannot find the command, give the full
path (e.g. `C:\\Users\\you\\.local\\bin\\turbogen-mcp.exe`).

## Claude Code

```bash
claude mcp add turbogen --env TURBOGEN_API_KEY=lk_your_key_here -- uvx turbogen-mcp
# installed with pipx instead:
claude mcp add turbogen --env TURBOGEN_API_KEY=lk_your_key_here -- turbogen-mcp
```

Add `--scope user` to make it available in every project. Check with `claude mcp list`.

## Cursor

Create `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for all projects):

```json
{
  "mcpServers": {
    "turbogen": {
      "command": "uvx",
      "args": ["turbogen-mcp"],
      "env": {
        "TURBOGEN_API_KEY": "lk_your_key_here",
        "TURBOGEN_OUTPUT_DIR": "~/Downloads/turbogen"
      }
    }
  }
}
```

## Try it

Ask your assistant things like:

- "List the Turbogen video models and their prices."
- "Generate a 16:9 image of a lighthouse at dusk with nano-banana-2."
- "Turn ~/Downloads/turbogen/lighthouse.png into an 8 second Veo clip with a slow push-in."
- "Make a 5 second sound effect of waves on rocks."
- "How many credits do I have left?"

## Errors

- *Not enough credits* (402): top up at `<base>/#/pricing`.
- *Invalid API key* (401): the key is wrong, revoked, or the account has no API access.
- *Model unavailable* (503): try another model or retry later.
- *Rate limited* (429): up to 30 jobs per minute and 3 running at once.
- Failed generations are refunded automatically.

## Links

- Website and pricing: https://turbogen.app/pricing
- API reference: https://turbogen.app/api-docs
- Support: hello@turbogen.app
