# Shotstack MCP Server

[![npm version](https://img.shields.io/npm/v/@shotstack/shotstack-mcp-server.svg)](https://www.npmjs.com/package/@shotstack/shotstack-mcp-server)

:::info Beta
The Shotstack MCP server is currently in beta. Tools and behaviour may change without notice.
:::

A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets any MCP-aware AI client compose and render Shotstack videos from natural language.

```
Endpoint:  https://mcp.shotstack.io/   (HTTP/streamable, OAuth)
Local:     npx -y @shotstack/shotstack-mcp-server   (stdio, SHOTSTACK_API_KEY env)
```

Get an API key at [app.shotstack.io](https://app.shotstack.io).

## Add it to your client

### Claude.ai · Claude Desktop

Settings → **Connectors** → Add custom connector → URL `https://mcp.shotstack.io/` → complete OAuth.

### Claude Code

```sh
claude mcp add --transport http shotstack https://mcp.shotstack.io
```

### ChatGPT

Settings → **Connectors** → Advanced → enable Developer mode → Create → URL `https://mcp.shotstack.io/`. Developer mode requires Business, Enterprise, or Edu.

### Cursor

`~/.cursor/mcp.json`:

```json
{ "mcpServers": { "shotstack": { "url": "https://mcp.shotstack.io/" } } }
```

### VS Code (GitHub Copilot)

`.vscode/mcp.json` (VS Code 1.101+):

```json
{ "servers": { "shotstack": { "type": "http", "url": "https://mcp.shotstack.io/" } } }
```

### Codex CLI

```sh
codex mcp add shotstack --url https://mcp.shotstack.io
```

### Gemini CLI

```sh
gemini mcp add -s user --transport http shotstack https://mcp.shotstack.io/
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{ "mcpServers": { "shotstack": { "serverUrl": "https://mcp.shotstack.io/" } } }
```

### Zed

`settings.json`:

```json
{ "context_servers": { "shotstack": { "url": "https://mcp.shotstack.io/" } } }
```

### JetBrains IDEs

Settings → **Tools** → MCP → Add → URL `https://mcp.shotstack.io/`.

### Goose

`goose configure` → Add extension → **Remote Extension (Streaming HTTP)** → URL `https://mcp.shotstack.io/`.

### Raycast

Extensions → MCP → Add server → URL `https://mcp.shotstack.io/`.

### Local stdio (fallback)

For offline use or if your client doesn't support HTTP transport, run the server locally:

```json
{
  "mcpServers": {
    "shotstack": {
      "command": "npx",
      "args": ["-y", "@shotstack/shotstack-mcp-server"],
      "env": { "SHOTSTACK_API_KEY": "your_api_key" }
    }
  }
}
```

## What it does

| Tool | Purpose |
|---|---|
| `studio` | Mounts the inline Studio canvas in the chat. **Default for chat clients** — user clicks Render in the iframe. |
| `render_video` | Submits an Edit JSON to the render API directly. Use for automation or when the user says "just render it". |
| `get_render_status` | Polls a render. Returns `queued`/`fetching`/`rendering`/`saving`/`done`/`failed` and the output URL. |
| `create_studio_link` | Generates a `https://shotstack.studio/s/{slug}` short link for sharing. |
| `get_shotstack_guide` | Returns the Edit JSON authoring conventions. |
| `create_template`, `list_templates`, `get_template`, `render_template`, `delete_template` | Manage reusable templates with `{{PLACEHOLDER}}` merge fields. |

## How agents should use it

1. **Call `get_shotstack_guide` before composing Edit JSON.** Track ordering, asset types, fonts, and the top-5 mistakes are non-negotiable. The full ruleset is at [`/agents/conventions`](/agents/conventions).
2. **Default to `studio`, not `render_video`.** Mount the edit inline so the user can preview and click Render. Only call `render_video` directly when explicitly asked or when there's no human in the loop.
3. **Use public HTTPS URLs for assets.** Never hallucinate URLs; ask the user when unsure.