storykit-mcp
by aryan0078
README.md
# storykit-mcp
Give an AI structured data and get back a hosted StoryKit widget — or drive the **full Studio** (images, media, brands, canvases, assets, series, workflows) with a personal API key.
1. **Public widgets (no key)** — `find_widgets` → `render_widget` → opaque hosted URL.
2. **Studio tools (`STORYKIT_API_KEY`)** — full owner surface under plan limits (~69 remote tools).
Mint a key + paste-ready LLM prompt: **[asset.storykit.space/ai](https://asset.storykit.space/ai)**
## CRITICAL: which endpoint?
| URL | Auth | Tools |
| --- | --- | --- |
| **`https://asset.storykit.space/api/v1/studio-mcp`** | `Bearer sk_live_…` | Full Studio (images included) |
| `https://asset.storykit.space/api/v1/mcp` | none | **Only** widgets (3 tools) — **no images** |
If `tools/list` lacks `generate_image`, you are on the wrong server.
## Connect
### Remote Studio (HTTP — preferred for images)
```bash
export STORYKIT_API_KEY="sk_live_…"
# Claude / Cursor / any streamable-HTTP MCP client:
# URL: https://asset.storykit.space/api/v1/studio-mcp
# Header: Authorization: Bearer $STORYKIT_API_KEY
```
```bash
claude mcp add --transport http storykit-studio https://asset.storykit.space/api/v1/studio-mcp \
--header "Authorization: Bearer ${STORYKIT_API_KEY}"
```
### Remote public widgets only
```bash
claude mcp add --transport http storykit https://asset.storykit.space/api/v1/mcp
```
### Local stdio (widgets always; Studio when key is set)
```bash
export STORYKIT_API_KEY="sk_live_…" # required for image/studio tools
claude mcp add storykit -- npx -y storykit-mcp@3.3.0
```
Stdio tool names are prefixed with `studio_` (e.g. `studio_generate_image` → remote `generate_image`).
## HARD RULES for agents
1. **Never invent images** with DALL·E, Midjourney, Gemini image, built-in `image_gen`, Unsplash, etc.
2. **Never invent ids** — call `list_*` / `get_*` first.
3. After `generate_image` / `edit_image`, poll `get_image_job` until **SUCCEEDED**; return platform `outputUrl` only.
## Public tools (no key)
| Tool | Spec |
| --- | --- |
| `find_widgets` | `{ intent, domain?, dataFields?, kind?, page?, size? }` → schemas only |
| `render_widget` | `{ widgetId, data[], theme?, ttlDays? }` → expiring hosted URL (treat as secret) |
| `list_widget_themes` | `{}` palettes |
Consent before personal/health data. Max 200 rows. Default TTL 30 days.
## Studio tools (`STORYKIT_API_KEY`)
Call `studio_get_account` or `studio_get_usage` first.
### Account & image status
| Tool | Spec |
| --- | --- |
| `studio_get_account` | `{}` identity, plan, quotas |
| `studio_get_usage` | `{}` full limits snapshot |
| `studio_get_image_status` | `{}` queue, aspects, remaining |
### Media library
| Tool | Spec |
| --- | --- |
| `studio_upload_media` | `{ imageBase64, contentType?, filename? }` → mediaId |
| `studio_list_media` | `{ query?, kind?, trash? }` |
| `studio_get_media` | `{ id }` |
| `studio_get_media_content` | `{ id }` base64 ≤2MB |
| `studio_update_media` | `{ id, title?, tags? }` |
| `studio_star_media` | `{ id, starred }` |
| `studio_trash_media` / `studio_restore_media` / `studio_delete_media` | `{ id }` |
### Image AI
| Tool | Aliases | Spec |
| --- | --- | --- |
| `studio_generate_image` | `studio_image_generate`, `studio_img_generate` | `{ prompt, aspect?, qualityMode?, brandKitId?, referenceMediaIds?, count?, magicPrompt?, caption?, mode? }` |
| `studio_edit_image` | `studio_image_edit`, `studio_img_edit` | `{ prompt, referenceMediaIds[1..5], maskMediaId?, aspect?, count? }` |
| `studio_list_images` | | `{ query?, state? }` |
| `studio_get_image_job` | | `{ jobId? }` or `{ id? }` — poll until SUCCEEDED |
| `studio_cancel_image_job` / `retry` / `delete` | | `{ jobId }` |
| `studio_describe_image` | | `{ mediaId? }` or `{ generationId? }` |
| `studio_publish_image` / `unpublish` | | `{ id }` numeric generation id |
| `studio_save_image_as_kit` | | `{ jobId }` |
| `studio_batch_generate_images` | | PRO: `{ prompts[], aspect?, brandKitId?, qualityMode? }` |
**Aspects:** `square` `portrait` `poster` `story` `landscape` `banner`
**qualityMode:** `fast` | `quality`
#### Image workflow
1. `studio_get_account`
2. Optional `studio_upload_media` → mediaId
3. `studio_generate_image` or `studio_edit_image`
4. Loop `studio_get_image_job` until SUCCEEDED
5. Return platform `outputUrl` only
### Prompt / vision
| Tool | Spec |
| --- | --- |
| `studio_compile_prompt` | `{ draft }` → caption for generate_image.caption |
| `studio_analyze_image_to_prompt` | `{ imageBase64, contentType?, aspect?, layout? }` |
| `studio_get_vision_job` | `{ jobId, apply? }` |
### Brands
| Tool | Spec |
| --- | --- |
| `studio_list_brand_kits` | `{ query?, page?, size? }` |
| `studio_get_brand_kit` | `{ id }` |
| `studio_extract_brand_kit` | `{ imagesBase64:[{base64,contentType?}], prompt?, md? }` |
| `studio_refine_brand_kit` | `{ id, feedback }` |
| `studio_rename_brand_kit` | `{ id, name }` |
| `studio_duplicate_brand_kit` | `{ id, name? }` |
| `studio_delete_brand_kit` | `{ id }` |
| `studio_publish_brand_kit` / `unpublish` | `{ id }` |
| `studio_brand_showcase` | `{ id, count? }` |
### Canvases
| Tool | Spec |
| --- | --- |
| `studio_list_canvases` | `{}` |
| `studio_get_canvas` | `{ id }` includes doc |
| `studio_create_canvas` | `{ title?, aspect? }` |
| `studio_save_canvas` | `{ id, title?, aspect?, doc?, thumbnailMediaId? }` |
| `studio_duplicate_canvas` / `studio_delete_canvas` | `{ id }` |
### Studio assets (commissioned widgets)
| Tool | Spec |
| --- | --- |
| `studio_list_studio_assets` | `{}` |
| `studio_get_studio_asset` | `{ id }` no source code |
| `studio_commission_studio_asset` | `{ prompt, kind?, purpose?, sourceMd? }` |
| `studio_iterate_studio_asset` | `{ id, feedback }` |
| `studio_rename_studio_asset` | `{ id, title }` |
| `studio_trash_studio_asset` / `restore` | `{ id }` |
| `studio_list_folders` / `studio_create_folder` | create: `{ name }` |
### Series & workflows
| Tool | Spec |
| --- | --- |
| `studio_list_series` / `get` / `create` / `series_next` / `series_extend` / `delete` | see input schemas |
| `studio_list_workflows` / `get` / `create` / `update` / `run` / `delete` / `list_workflow_runs` | |
Remote names drop the `studio_` prefix. Full list: `tools/list` on studio-mcp.
Track usage at [storykit.space/me](https://storykit.space/me).
## Environment
| Variable | Purpose |
| --- | --- |
| `STORYKIT_API_BASE` | API host (default `https://asset.storykit.space`) |
| `STORYKIT_API_KEY` | Personal `sk_live_…` for Studio tools |
| `STORYKIT_STUDIO_MCP` | Override Studio MCP URL |
MIT. Created with love by [Story Kit](https://storykit.space).
TDQS
A4.2/5.0
Scored across 7 tools
Disambiguation5/5
Each tool targets a distinct function: bundle URL generation, asset retrieval, embedding, and various listing/search operations. No overlapping purposes.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern with lowercase underscores (bundle_url, get_asset, list_chart_families, etc.), making naming predictable.
Tool Count5/5
7 tools cover key operations without redundancy, suitable for a design library and bundle generation service.
Completeness4/5
Covers retrieval, search, and bundle creation for assets, but lacks tools for creating, updating, or managing assets, which may be intentional but leaves some gaps.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues