turbogen-mcp 0.1.0__tar.gz

turbogen_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+data/
+__pycache__/
+*.pyc
+gpu-worker/models/
+gpu-worker/token.txt
+gpu-worker/venv/
+gpu-worker/logs/
+tests/gpu_live/

turbogen_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Turbogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

turbogen_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: turbogen-mcp
+Version: 0.1.0
+Summary: MCP server for generating images, video and audio through the Turbogen API
+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

turbogen_mcp-0.1.0/README.md

@@ -0,0 +1,133 @@
+# 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

turbogen_mcp-0.1.0/README.md.bak1111

@@ -0,0 +1,129 @@
+# Turbogen MCP server
+
+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 --from /path/to/mcp-server turbogen-mcp
+```
+
+Or install the command once with pipx (or uv tool):
+
+```bash
+pipx install /path/to/mcp-server      # or: uv tool install /path/to/mcp-server
+turbogen-mcp                            # waits for an MCP client on stdin; Ctrl+C to quit
+```
+
+Plain venv:
+
+```bash
+python -m venv .venv
+.venv/bin/pip install .               # Windows: .venv\Scripts\pip install .
+```
+
+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": ["--from", "/path/to/mcp-server", "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 --from /path/to/mcp-server 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": ["--from", "/path/to/mcp-server", "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.
+
+## Rebranding
+
+The brand name and default host are the `BRAND` and `DEFAULT_BASE_URL` constants at the top of `server.py`.

turbogen_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "turbogen-mcp"
+version = "0.1.0"
+description = "MCP server for generating images, video and audio through the Turbogen API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Turbogen", email = "hello@turbogen.app" }]
+keywords = ["mcp", "model-context-protocol", "ai-video", "ai-image", "veo", "seedance", "kling", "nano-banana", "claude"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "mcp>=1.2",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://turbogen.app"
+Documentation = "https://turbogen.app/api-docs#mcp"
+Pricing = "https://turbogen.app/pricing"
+
+[project.scripts]
+turbogen-mcp = "server:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["server.py", "LICENSE"]

turbogen_mcp-0.1.0/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "app.turbogen/turbogen",
+  "title": "Turbogen",
+  "description": "Generate images, video and audio (Veo 3.1, Seedance, Kling, Nano Banana Pro) pay-as-you-go.",
+  "websiteUrl": "https://turbogen.app/api-docs#mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "turbogen-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        { "name": "TURBOGEN_API_KEY", "description": "API key from https://turbogen.app/#/apikeys (starts with lk_)", "isRequired": true, "isSecret": true },
+        { "name": "TURBOGEN_OUTPUT_DIR", "description": "Folder for downloaded results (default ~/Downloads/turbogen)", "isRequired": false }
+      ]
+    }
+  ]
+}

turbogen_mcp-0.1.0/server.py

@@ -0,0 +1,378 @@
+"""Turbogen MCP server: generate images, video and audio through the Turbogen API from any MCP client.
+
+Config (environment):
+  TURBOGEN_API_KEY     required, an API key starting with lk_
+  TURBOGEN_BASE_URL    optional, defaults to DEFAULT_BASE_URL
+  TURBOGEN_OUTPUT_DIR  optional, defaults to ~/Downloads/turbogen
+"""
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import os
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+try:                                   # mcp 1.x
+    from mcp.server.fastmcp import FastMCP, Image
+except ImportError:                    # mcp 2.x renamed FastMCP -> MCPServer (same decorator API)
+    from mcp.server.mcpserver import Image, MCPServer as FastMCP
+
+# Brand / host live here only - change these two lines on a rename.
+BRAND = "Turbogen"
+DEFAULT_BASE_URL = "https://turbogen.app"
+
+POLL_EVERY_S = 3
+POLL_TIMEOUT_S = 600
+INLINE_IMAGE_MAX_BYTES = 1_000_000
+
+mcp = FastMCP(f"{BRAND.lower()}")
+
+
+# ---------- config & http ----------
+
+class TurbogenError(Exception):
+    pass
+
+
+def _base() -> str:
+    return os.environ.get("TURBOGEN_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def _key() -> str:
+    k = os.environ.get("TURBOGEN_API_KEY", "").strip()
+    if not k:
+        raise TurbogenError("TURBOGEN_API_KEY is not set. Create a key on the API page of "
+                          f"{_base()}/#/apikeys and add it to the MCP server config.")
+    return k
+
+
+def _out_dir() -> Path:
+    d = Path(os.environ.get("TURBOGEN_OUTPUT_DIR") or Path.home() / "Downloads" / BRAND.lower()).expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _client(auth: bool = True) -> httpx.AsyncClient:
+    headers = {"User-Agent": f"{BRAND.lower()}-mcp/0.1"}
+    if auth:
+        headers["Authorization"] = f"Bearer {_key()}"
+    return httpx.AsyncClient(base_url=_base(), headers=headers, timeout=httpx.Timeout(120, connect=15),
+                             follow_redirects=True)
+
+
+def _raise_for(r: httpx.Response) -> None:
+    if r.is_success:
+        return
+    try:
+        detail = r.json().get("detail")
+    except Exception:
+        detail = None
+    detail = detail if isinstance(detail, str) else (r.text[:300] or r.reason_phrase)
+    if r.status_code == 402:
+        raise TurbogenError(f"Not enough credits, top up at {_base()}/#/pricing")
+    if r.status_code == 401:
+        raise TurbogenError(f"Invalid API key ({detail}). Check TURBOGEN_API_KEY; keys are managed at {_base()}/#/apikeys")
+    if r.status_code == 503:
+        raise TurbogenError(f"Model unavailable: {detail}")
+    if r.status_code == 429:
+        raise TurbogenError(f"Rate limited: {detail}")
+    raise TurbogenError(f"API error {r.status_code}: {detail}")
+
+
+_models_cache: dict[str, Any] = {"t": 0.0, "data": None}
+
+
+async def _catalog() -> dict:
+    if _models_cache["data"] and time.time() - _models_cache["t"] < 300:
+        return _models_cache["data"]
+    # /api/models is public; API keys are accepted on /api/jobs only.
+    async with _client(auth=False) as c:
+        r = await c.get("/api/models")
+    _raise_for(r)
+    _models_cache.update(t=time.time(), data=r.json())
+    return _models_cache["data"]
+
+
+async def _model(model_id: str, kind: str | None = None) -> dict:
+    cat = await _catalog()
+    for m in cat["models"]:
+        if m["id"] == model_id:
+            if kind and m["kind"] != kind:
+                raise TurbogenError(f"'{model_id}' is a {m['kind']} model, not {kind}. Use list_models(kind='{kind}').")
+            return m
+    ids = ", ".join(m["id"] for m in cat["models"] if not kind or m["kind"] == kind)
+    raise TurbogenError(f"Unknown model '{model_id}'. Available: {ids}")
+
+
+def _pick(value: str | None, allowed: list[str], label: str, model_id: str) -> str:
+    if not value:
+        return allowed[0]
+    if value in allowed:
+        return value
+    for a in allowed:                      # forgiving case-insensitive match ("4k" -> "4K")
+        if a.lower() == value.lower():
+            return a
+    raise TurbogenError(f"{label} '{value}' is not supported by {model_id}. Choose one of: {', '.join(allowed)}")
+
+
+def _ref_file(path: str) -> tuple[str, bytes, str]:
+    p = Path(path).expanduser()
+    if not p.is_file():
+        raise TurbogenError(f"File not found: {p}")
+    mime = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
+    if mime not in ("image/png", "image/jpeg", "image/webp"):
+        raise TurbogenError(f"{p.name}: only PNG, JPEG or WEBP images are accepted")
+    return (p.name, p.read_bytes(), mime)
+
+
+# ---------- job flow ----------
+
+async def _find_job(c: httpx.AsyncClient, job_id: str) -> tuple[dict | None, int]:
+    r = await c.get("/api/jobs", params={"limit": 200})
+    _raise_for(r)
+    data = r.json()
+    return next((j for j in data["jobs"] if j["id"] == job_id), None), data.get("credits")
+
+
+def _slug(s: str, n: int = 40) -> str:
+    s = re.sub(r"[^A-Za-z0-9]+", "-", s).strip("-").lower()
+    return s[:n].strip("-") or "result"
+
+
+async def _run_job(fields: dict[str, str], refs: list[str], label: str) -> dict:
+    files = [("refs", _ref_file(p)) for p in refs]
+    async with _client() as c:
+        r = await c.post("/api/jobs", data=fields, files=files or None)
+        _raise_for(r)
+        sub = r.json()
+        job = sub["job"]
+        credits = sub.get("credits")
+        deadline = time.monotonic() + POLL_TIMEOUT_S
+        while job["status"] in ("queued", "running"):
+            if time.monotonic() > deadline:
+                raise TurbogenError(f"Job {job['id']} still {job['status']} after {POLL_TIMEOUT_S // 60} min. "
+                                  f"Check later with job_status('{job['id']}').")
+            await asyncio.sleep(POLL_EVERY_S)
+            found, credits = await _find_job(c, job["id"])
+            if found:
+                job = found
+        if job["status"] != "done":
+            raise TurbogenError(f"Generation failed: {job.get('note') or 'no reason given'} "
+                              f"(job {job['id']}; failed jobs are refunded automatically). Credits: {credits}")
+        path = await _download(c, job, label)
+    return {"job_id": job["id"], "path": str(path), "mime": job.get("mime"), "cost": job.get("cost"),
+            "credits_left": credits}
+
+
+async def _download(c: httpx.AsyncClient, job: dict, label: str) -> Path:
+    r = await c.get(job["url"] or f"/api/jobs/{job['id']}/file")
+    _raise_for(r)
+    mime = (job.get("mime") or r.headers.get("content-type", "")).split(";")[0]
+    ext = {"image/jpeg": ".jpg", "audio/mpeg": ".mp3"}.get(mime) or mimetypes.guess_extension(mime) or ".bin"
+    path = _out_dir() / f"{job['model']}-{_slug(label)}-{job['id'][:8]}{ext}"
+    path.write_bytes(r.content)
+    return path
+
+
+def _summary(res: dict) -> str:
+    return (f"Saved: {res['path']}\nCost: {res['cost']} credits · Credits left: {res['credits_left']}"
+            f"\nJob: {res['job_id']}")
+
+
+def _with_image(res: dict) -> list:
+    out: list = [_summary(res)]
+    p = Path(res["path"])
+    if (res.get("mime") or "").startswith("image/") and p.stat().st_size <= INLINE_IMAGE_MAX_BYTES:
+        out.append(Image(path=p))
+    return out
+
+
+def _err(e: Exception) -> str:
+    if isinstance(e, TurbogenError):
+        return f"Error: {e}"
+    if isinstance(e, httpx.HTTPError):
+        return f"Error: could not reach {_base()} ({e.__class__.__name__}: {e})"
+    raise e
+
+
+# ---------- tools ----------
+
+@mcp.tool()
+async def list_models(kind: str | None = None) -> str:
+    """List available generation models with their ids, aspect/voice choices, options and credit prices.
+
+    kind: optional filter - "image", "video" or "audio".
+    """
+    try:
+        cat = await _catalog()
+        rate = cat.get("usd_per_credit")
+        lines = [f"{BRAND} models (1 credit ≈ ${rate})" if rate else f"{BRAND} models"]
+        for m in cat["models"]:
+            if kind and m["kind"] != kind.lower():
+                continue
+            prices = ", ".join(f"{o}={c}cr" for o, c in m["prices"].items())
+            bits = [f"- {m['id']} [{m['kind']}] {m['name']}",
+                    f"  {m.get('aspect_label', 'Aspect')}: {', '.join(m['aspects'])}",
+                    f"  {m.get('option_label', 'Option')}: {prices}"]
+            extra = []
+            if m.get("max_refs"):
+                extra.append(f"refs≤{m['max_refs']}")
+            if m.get("needs_ref"):
+                extra.append("needs an input image")
+            if m.get("lyrics"):
+                extra.append(f"lyrics for: {', '.join(m['lyrics'])}")
+            if not m.get("available", True):
+                extra.append("UNAVAILABLE now")
+            if extra:
+                bits.append("  " + " · ".join(extra))
+            if m.get("tagline"):
+                bits.append(f"  {m['tagline']}")
+            lines.append("\n".join(bits))
+        return "\n".join(lines)
+    except Exception as e:
+        return _err(e)
+
+
+@mcp.tool()
+async def generate_image(prompt: str, model: str = "nano-banana-2", aspect: str = "1:1",
+                         option: str | None = None, reference_images: list[str] | None = None) -> list:
+    """Generate an image and save it locally. Returns the file path, cost and remaining credits (plus a preview).
+
+    prompt: what to draw.
+    model: image model id (see list_models(kind="image")), default nano-banana-2.
+    aspect: aspect ratio, e.g. "1:1", "16:9", "9:16".
+    option: resolution/quality option such as "1K", "2K", "4K"; defaults to the model's first (cheapest) option.
+    reference_images: optional list of local PNG/JPEG/WEBP paths used as references.
+    """
+    try:
+        m = await _model(model, "image")
+        if m.get("needs_ref"):
+            return [f"Error: {model} is a tool, not a generator. Use upscale_image for it."]
+        refs = reference_images or []
+        if len(refs) > m.get("max_refs", 0):
+            return [f"Error: {m['name']} accepts up to {m.get('max_refs', 0)} reference images"]
+        fields = {"model": model, "prompt": prompt, "aspect": _pick(aspect, m["aspects"], "Aspect", model),
+                  "option": _pick(option, list(m["prices"]), m.get("option_label", "Option"), model)}
+        return _with_image(await _run_job(fields, refs, prompt))
+    except Exception as e:
+        return [_err(e)]
+
+
+@mcp.tool()
+async def generate_video(prompt: str, model: str = "veo-3.1-fast", aspect: str = "16:9",
+                         option: str = "8s", image_path: str | None = None) -> str:
+    """Generate a video clip and save it locally. Returns the file path, cost and remaining credits.
+
+    prompt: the shot - subject, action, camera move, light.
+    model: video model id (see list_models(kind="video")), default veo-3.1-fast.
+    aspect: "16:9", "9:16" (some models also "1:1" etc.).
+    option: duration such as "4s", "6s", "8s"; must be one the model offers.
+    image_path: optional local image for image-to-video (first frame / reference).
+    Video takes 1-5 minutes; the call waits up to 10 minutes.
+    """
+    try:
+        m = await _model(model, "video")
+        refs = [image_path] if image_path else []
+        if refs and not m.get("max_refs"):
+            return f"Error: {m['name']} does not accept an input image"
+        opts = list(m["prices"])
+        if option == "8s" and option not in opts:   # default doesn't fit this model -> its first duration
+            option = None
+        fields = {"model": model, "prompt": prompt, "aspect": _pick(aspect, m["aspects"], "Aspect", model),
+                  "option": _pick(option, opts, "Duration", model)}
+        return _summary(await _run_job(fields, refs, prompt))
+    except Exception as e:
+        return _err(e)
+
+
+@mcp.tool()
+async def generate_audio(text_or_prompt: str, model: str = "voice", aspect: str | None = None,
+                         option: str | None = None, lyrics: str | None = None) -> str:
+    """Generate audio (voiceover, background music, a song or a sound effect) and save it locally.
+
+    text_or_prompt: for "voice" the text to speak; for "music"/"song"/"sfx" a description of the sound.
+    model: "voice" (text to speech), "music" (instrumental background), "song" (sung, needs lyrics) or "sfx".
+    aspect: the voice for "voice" (e.g. "Deep narrator", "Warm female"), the mood for "music" (e.g. "Cinematic",
+            "Lo-fi"), the vocal for "song" ("Female vocal", "Male vocal", "Duet"); defaults to the first choice.
+            See list_models(kind="audio").
+    option: length/duration, e.g. "300 chars" for voice, "30s" for music, "60s" for song, "5s" for sfx; defaults to the first.
+    lyrics: song lyrics, required for "song".
+    """
+    try:
+        m = await _model(model, "audio")
+        fields = {"model": model, "prompt": text_or_prompt,
+                  "aspect": _pick(aspect, m["aspects"], m.get("aspect_label", "Aspect"), model),
+                  "option": _pick(option, list(m["prices"]), m.get("option_label", "Option"), model)}
+        if fields["aspect"] in (m.get("lyrics") or []):
+            if not lyrics:
+                return f"Error: '{fields['aspect']}' needs lyrics. Pass lyrics or use aspect='Instrumental'."
+            fields["lyrics"] = lyrics
+        return _summary(await _run_job(fields, [], text_or_prompt))
+    except Exception as e:
+        return _err(e)
+
+
+@mcp.tool()
+async def upscale_image(path: str, scale: str = "2x") -> list:
+    """Upscale a local image 2x or 4x and save the result next to other outputs.
+
+    path: local PNG/JPEG/WEBP file.
+    scale: "2x" or "4x".
+    """
+    try:
+        m = await _model("upscale", "image")
+        fields = {"model": "upscale", "prompt": "", "aspect": m["aspects"][0],
+                  "option": _pick(scale, list(m["prices"]), "Scale", "upscale")}
+        return _with_image(await _run_job(fields, [path], Path(path).stem + "-" + fields["option"]))
+    except Exception as e:
+        return [_err(e)]
+
+
+@mcp.tool()
+async def get_balance() -> str:
+    """Show the remaining credit balance of the account behind TURBOGEN_API_KEY."""
+    try:
+        async with _client() as c:
+            r = await c.get("/api/jobs", params={"limit": 1})
+        _raise_for(r)
+        credits = r.json().get("credits")
+        rate = (await _catalog()).get("usd_per_credit")
+        usd = f" (≈ ${credits * rate:.2f})" if rate and credits is not None else ""
+        return f"Credits: {credits}{usd}. Top up at {_base()}/#/pricing"
+    except Exception as e:
+        return _err(e)
+
+
+@mcp.tool()
+async def job_status(job_id: str, download: bool = False) -> str:
+    """Check a generation job by id (e.g. one that outlived the 10-minute wait).
+
+    download: if true and the job is done, save its file to the output folder and return the path.
+    """
+    try:
+        async with _client() as c:
+            job, credits = await _find_job(c, job_id)
+            if not job:
+                return f"Error: job {job_id} not found among your 200 most recent jobs"
+            lines = [f"Job {job['id']}: {job['status']}", f"Model: {job['model']} · Cost: {job.get('cost')} credits",
+                     f"Created: {job.get('created_at')}"]
+            if job.get("note"):
+                lines.append(f"Note: {job['note']}")
+            if job["status"] == "done" and download:
+                lines.append(f"Saved: {await _download(c, job, job.get('prompt') or 'result')}")
+            lines.append(f"Credits left: {credits}")
+            return "\n".join(lines)
+    except Exception as e:
+        return _err(e)
+
+
+def main() -> None:
+    mcp.run()  # stdio transport
+
+
+if __name__ == "__main__":
+    main()