clipstudio-mcp

<p align="center">
  <img src="https://clipstudio.ai/logo-mark.png" alt="Clip Studio" width="72" height="72">
</p>

# Clip Studio MCP

Hosted [Model Context Protocol](https://modelcontextprotocol.io) server for Clip Studio. Add one URL to Claude, Cursor, ChatGPT, or any MCP client and use the **same public Clip Studio products a signed-in human already has** — Video Lab, Topic Shorts, Talking Shorts, Ad Studio, Last Frame, Image Lab, Audio Lab, Story, Ad Lab, library, and free tools — on the **same plan as the website**.

**Endpoint:** `https://clipstudio.ai/api/mcp`  
**Transport:** Streamable HTTP  
**Marketing:** [https://clipstudio.ai/mcp](https://clipstudio.ai/mcp)  
**Public tool list:** [https://clipstudio.ai/mcp.md](https://clipstudio.ai/mcp.md)  
**Repository:** [https://github.com/j-acks0n/clipstudio-mcp](https://github.com/j-acks0n/clipstudio-mcp)  
**Smithery:** [https://smithery.ai/servers/clipstudioai/clipstudio](https://smithery.ai/servers/clipstudioai/clipstudio)

[![smithery badge](https://smithery.ai/badge/clipstudioai/clipstudio)](https://smithery.ai/servers/clipstudioai/clipstudio)

This repo is a connector listing (`server.json`, install snippets, examples). The server is hosted. There is nothing to clone and run.

## Quick start

Paste the URL. Leave OAuth client id empty. Sign in when the client opens Clip Studio, then Approve.

### Claude Desktop / Claude.ai connectors

Customize → Connectors → Add custom connector. Paste:

```
https://clipstudio.ai/api/mcp
```

Connect. Leave OAuth client id empty.

### Cursor

Add an HTTP MCP server in `~/.cursor/mcp.json`. Cursor runs OAuth on first use.

```json
{
  "mcpServers": {
    "clipstudio": {
      "url": "https://clipstudio.ai/api/mcp"
    }
  }
}
```

### ChatGPT (developer mode connector)

Enable developer mode, add a custom MCP connector, paste `https://clipstudio.ai/api/mcp`, then complete Clip Studio Approve.

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json` (remote field is `serverUrl`):

```json
{
  "mcpServers": {
    "clipstudio": {
      "serverUrl": "https://clipstudio.ai/api/mcp"
    }
  }
}
```

Save, then refresh MCP in Cascade.

### VS Code / Copilot

User or workspace `mcp.json`:

```json
{
  "servers": {
    "clipstudio": {
      "type": "http",
      "url": "https://clipstudio.ai/api/mcp"
    }
  }
}
```

Command Palette → **MCP: Open User Configuration**, or `.vscode/mcp.json` in a workspace.

### Stdio-only clients

Bridge to Streamable HTTP:

```bash
npx -y mcp-remote https://clipstudio.ai/api/mcp
```

Example wrapper:

```json
{
  "mcpServers": {
    "clipstudio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://clipstudio.ai/api/mcp"]
    }
  }
}
```

## Authentication

One-click OAuth on the first call. Unauthenticated requests — including `initialize` and `tools/list` — return HTTP **401** with `WWW-Authenticate` and protected-resource metadata. The client dynamically registers (OAuth 2.1 + PKCE, public client). You sign in with the Clip Studio account and Approve. Tokens stay on the client.

No client id to paste. If a human cannot do the job on [clipstudio.ai](https://clipstudio.ai), the agent cannot do it here.

## How a paid job works

1. **Quote** (`quote_*`). Does not generate.
2. If the monthly generation allowance cannot cover the quote, the tool returns HTTP **402** with numeric JSON fields (names only — these are API keys, not UI copy):

   ```json
   {
     "requiredCredits": 120,
     "availableCredits": 0
   }
   ```

   Then call `create_checkout_url` with a `priceId` from `get_account.offerCheckout`. It returns a Stripe Checkout URL and does not take card data.
3. **Generate** (`generate_*` / `start_last_frame` / `render_storyboard` / …). Uses this month’s generation allowance.
4. **Poll** the matching `get_*` tool until the job finishes.

Submit and poll. Do not hold the MCP request for a full provider render.

## Example prompts

- Preview a 15-second Topic Short about why most morning routines fail, then quote and generate it.
- List Video Lab models, quote an 8-second 16:9 clip of a running shoe on a wet track, generate, and poll until it is ready.
- Continue my story: load the latest project, write the next part, then render it.
- Check my remaining monthly generation allowance. If a quote returns 402, open checkout from `offerCheckout`.
- Research an Ad Studio clip from this product URL, pick a catalog creator, quote, generate, and poll.

Walkthroughs: [examples/](examples/).

## Tools

Names match [https://clipstudio.ai/mcp.md](https://clipstudio.ai/mcp.md). Paid tools use this month’s generation allowance.

### Video Lab

Frontier text- and image-to-video. Quote before generate.

| Tool | Description |
| --- | --- |
| `list_video_lab_models` | List models, modes, and defaults. Same catalog as `/video-lab`. |
| `quote_video_lab` | Quote a setup. Does not generate. Paid generate needs this quote. |
| `generate_video_lab` | Start a paid generation. Poll `get_video_lab_generation`. |
| `list_video_lab_generations` | List this account’s Video Lab generations. |
| `get_video_lab_generation` | Fetch one generation by video id. |
| `reconcile_video_lab_generation` | Refresh a job from the provider. Does not debit again. |
| `presign_generation_asset` | Create an upload slot for a source image or MP4. Then `complete_generation_asset`. |
| `complete_generation_asset` | Mark a source image or MP4 upload ready. |

### Topic Shorts

Topic → story + stock + voice. Caption mode default `current`. Transition mode default `dynamic`.

| Tool | Description |
| --- | --- |
| `list_hook_bank` | Opening hooks templates (Problem, Curiosity, Trust, Niche). Seeds topic/brief; not caption style. |
| `create_topic_short_story` | Preview beats, narration, and English stock queries. Does not render. |
| `quote_topic_short` | Quote a Topic Short. Does not render. Quoted on duration. |
| `generate_topic_short` | Generate from a topic or reviewed `storyPlan`. Poll `get_topic_short`. |
| `get_topic_short` | Fetch a generation. |

### Talking Shorts

Product URL or brief → talking-head clip. Catalog faces and voices.

| Tool | Description |
| --- | --- |
| `research_talking_short` | Research from a URL or brief. Does not render. |
| `quote_talking_short` | Quote a Talking Short. Does not render. |
| `generate_talking_short` | Start a paid Talking Short. Poll `get_talking_short`. |
| `get_talking_short` | Fetch a generation. |
| `list_talking_short_actors` | List catalog stills. Does not render. |

### Ad Studio

Product → angle → 5-beat script → catalog creator → one vertical clip.

| Tool | Description |
| --- | --- |
| `research_ad_studio` | Research angles and a locked 5-beat script. Does not render. |
| `quote_ad_studio` | Quote an Ad Studio job. Catalog creators only. |
| `generate_ad_studio` | Start a paid clip. Poll `get_ad_studio`. |
| `get_ad_studio` | Fetch a generation. Submit and poll. |

### Last Frame

Play a generated film. The last frame is canon.

| Tool | Description |
| --- | --- |
| `list_last_frame_games` | List games (Adventure, Heist, Tape, and the rest). |
| `list_last_frame_worlds` | List catalog worlds/maps. |
| `quote_last_frame` | Quote an opening or next shot. Does not film. |
| `start_last_frame` | Start a run and film the opening shot. |
| `get_last_frame_run` | Get a run, including the latest shot and choices. |
| `choose_last_frame` | Pick a numbered option. Films the next shot. |
| `type_last_frame` | Type a custom move. Films the next shot. |
| `timeout_last_frame` | Apply the choice timeout (HUD timer). |
| `end_last_frame_clip` | Tell the run the current shot finished playing. |
| `arm_last_frame_item` | Arm an inventory item for the next move (`itemIndex` is 0-based). |
| `create_last_frame_world` | Create a custom world from a description. |

### Image Lab

Quoted stills. Same catalog as `/image-lab`.

| Tool | Description |
| --- | --- |
| `list_image_lab_models` | List models, modes, and aspect ratios. |
| `quote_image_lab` | Quote a still. Does not generate. Paid generate needs this quote. |
| `generate_image_lab` | Start a paid still. Poll `get_image_lab_generation`. |
| `list_image_lab_generations` | List this account’s Image Lab generations. |
| `get_image_lab_generation` | Fetch one generation and refresh it from the provider. |

### Audio Lab

Script → downloadable narration with Clip Studio voices.

| Tool | Description |
| --- | --- |
| `list_audio_lab_voices` | List narration voices (accent and locale). |
| `quote_audio_lab` | Quote a script. Does not generate. |
| `generate_audio_lab` | Start paid narration. Poll `get_audio_lab_generation`. |
| `list_audio_lab_generations` | List this account’s Audio Lab generations. |
| `get_audio_lab_generation` | Fetch one generation and refresh it from the provider. |

### Story

Full story → parts → film. Continue my story on the **same** `projectId`.

| Tool | Description |
| --- | --- |
| `list_storyboard_themes` | List visual themes (carries across parts). |
| `list_storyboard_voices` | List narration voices (carries across parts). |
| `estimate_storyboard` | Estimate the next part from a script. Does not render. |
| `create_storyboard` | Start a project from a full story. Does not write a part or film. |
| `get_storyboard` | Fetch a project, or omit `projectId` to list recent ones. |
| `generate_storyboard_part` | Write the next part on an existing project. Does not film. |
| `render_storyboard` | Film the latest part. Poll `get_storyboard`. |

### Ad Lab

Website → static layouts, tip pack, Proof pack, or Explain film.

| Tool | Description |
| --- | --- |
| `import_ad_website` | Read a public website into a company profile. |
| `quote_ad` | Quote a static layout. Does not generate. |
| `generate_ad` | Generate stills (`layout` 9:16, 1:1, 4:5, or 16:9). Poll `get_ad_generation`. |
| `quote_ad_tip_pack` | Quote a tip pack. Does not generate. |
| `generate_ad_tip_pack` | Generate a tip pack. Poll `get_ad_