# Slates MCP Server [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/EricDisero/slates-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 785  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/slatesvideo-mcp-server

## Description
MCP server for the Slates desktop app. Your AI agent (ChatGPT via Codex, Claude, Cursor, or another local MCP client) drives a local AI video studio: projects, characters, storyboards, image and video generation. Files land on disk.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "slates-mcp-server": {
    "command": "npx",
    "args": ["-y","@slatesvideo/mcp-server"]
  }
}
```

## Documentation & README

# slates-mcp

MCP server + CLI + skills package for [Slates](https://slates.video) — drive the AI Video Creation Studio from ChatGPT via Codex, Claude Code, Cursor, Claude Desktop, or another local MCP client.

This monorepo publishes two installable packages, plus their shared core:

- **`@slatesvideo/mcp-server`** — stdio MCP server. Run with `npx -y @slatesvideo/mcp-server`.
- **`@slatesvideo/cli`** — `slates` binary. Run with `npm i -g @slatesvideo/cli`.
- **`@slatesvideo/shared`** — the operations layer both surfaces depend on (published as their dependency, not installed directly).

Agent-side recipe markdown ("skills") lives in `packages/shared/skills/` and is embedded into `@slatesvideo/shared` at build time — install into your project with `slates install-skills`, or (MCP-only clients) read any guide at runtime via the `slates_get_prompting_guide` tool.

## What it does

The MCP/CLI lets an AI agent control your Slates workspace end to end: create projects, build characters and boards, generate images and videos (blocking or in the background), surgically edit images, assemble clips on the editing timeline, export the result as an MP4 (or FCP7 XML for DaVinci Resolve), and watch the desktop app populate live as the agent works. <!-- gen:tool-count -->180<!-- /gen:tool-count --> tools total.

Both surfaces share one operations layer (`@slatesvideo/shared`) and one config file (`~/.slates/agent-connection.json`).

> **Desktop version note:** the timeline, export, background-generation, edit-image, and image-reference tools need a Slates desktop on agent API v2. If a tool reports a version error, update Slates (Settings → Check for Updates) and retry. Everything else works on older desktops.

## Setup

1. Install or update Slates desktop. Open it.
2. **Settings → AI tools → enter your email → Send link.** This one click starts the local HTTP server on `127.0.0.1:27272` (or the next free port) AND emails you a sign-in link.
3. Click the link in your email to authorize this machine.
4. The connection file is now written with both:
   - `desktop` — port + token for the local server
   - `cloud` — `slates_sk_` token for [slates-api](https://slates-api.fly.dev)

That's it. Both the CLI and the MCP auto-discover the connection file. No env vars, no copy-paste. (Need the local server without the cloud token? There's a raw server toggle under **Advanced** — most people don't need it.)

## Using it

### MCP server (ChatGPT via Codex / Claude / Cursor)

For **ChatGPT users**, sign in to the local Codex app or CLI with your ChatGPT account. With Slates open on the same computer, run:

```bash
codex mcp add slates -- npx -y @slatesvideo/mcp-server
```

Restart Codex. This connects local Codex; a regular ChatGPT web chat does not connect to this stdio server. [Connection guide](https://slates.video/docs/connect-claude).

For **Claude Desktop or Cursor**, add to your MCP config:

```json
{
  "mcpServers": {
    "slates": {
      "command": "npx",
      "args": ["-y", "@slatesvideo/mcp-server"]
    }
  }
}
```

Restart your client. Slates tools appear in the tool palette.

**Don't want to edit JSON?** The Slates desktop app writes the config for you — **Settings → AI tools → Connect** (one click per tool, no terminal). Or, from a terminal, `npx -y @slatesvideo/cli mcp --write` detects your clients, writes Claude Desktop/Cursor configs, and prints the Codex/Claude Code setup commands. For Claude Desktop you can also drop in the one-click **`.mcpb` bundle** from the [latest GitHub release](https://github.com/EricDisero/slates-mcp/releases/latest).

### CLI (Codex, Claude Code, terminal scripts)

**Fastest path — one command** wires the MCP config into supported detected clients, installs the skills, and points you at the account-connect step:

```bash
npx -y @slatesvideo/cli setup
```

Or step by step:

```bash
npm i -g @slatesvideo/cli
slates login                  # only if you haven't connected via Settings
slates install-skills         # installs the same skills for Claude Code and Codex
slates mcp --write            # detect clients, configure or print setup commands
slates status                 # show connection state
slates run --list             # list every operation
slates run slates_create_project --name "neon samurai"
```

In Codex or Claude Code, the agent shells out to `slates run <op> --key value` instead of loading <!-- gen:tool-count -->180<!-- /gen:tool-count --> tool schemas into context — `slates run <op> --help` prints one op's flags, and `--input '<json>'` carries the nested objects flags cannot.

The <!-- gen:skill-count -->43<!-- /gen:skill-count --> bundled skills provide higher-level recipes: <!-- gen:workflow-skill-count -->28<!-- /gen:workflow-skill-count --> workflow guides (<!-- gen:workflow-skills -->blocking-to-prompt, camera-language, captions, character-identity, chatgpt-images, cinematic-look, content-policy, cost-discipline, cuts, dialogue-blocking, direct-response-ad, edit-and-iterate, layer-brand-captions, layer-lower-third, layer-title, model-selection, motion, one-prompt-film, previs-blocking, project-organization, restyle-from-blocking, script-craft, shot-variety, storyboard-from-script, style-prompting, transitions, ugc-influencer-ad, vision-feedback-loop<!-- /gen:workflow-skills -->) and <!-- gen:per-model-skill-count -->15<!-- /gen:per-model-skill-count --> per-model prompting guides covering <!-- gen:video-roster -->kling-v3.0-std, kling-v3.0-pro, kling-v3.0-omni, Seedance 2.0, Seedance 2.5, Gemini Omni Flash, MiniMax H3, MiniMax H3 Max, MiniMax H3 Max Turbo, LTX-2.5, LTX-2.5 Pro<!-- /gen:video-roster --> for video, <!-- gen:image-roster -->Nano Banana 2 (Gemini 3.1 Flash Image), Nano Banana 2 Lite, Nano Banana Pro, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, FLUX.2 Max, Seedream 5 Lite<!-- /gen:image-roster --> for images, and <!-- gen:audio-roster -->Seed Audio 1.0, ElevenLabs Sound Effects v2, Inworld Realtime TTS-2<!-- /gen:audio-roster --> for audio.

## Architecture

```
~/.slates/agent-connection.json          ← single source of truth
        │
        ├── cloud.token   (slates_sk_)   ← carried in Authorization headers to slates-api
        └── desktop.{port,token}         ← carried in Authorization headers to 127.0.0.1:PORT

@slatesvideo/shared
    operations/index.ts                  ← single tool surface
    clients/cloud.ts                     ← https://slates-api.fly.dev
    clients/desktop.ts                   ← http://127.0.0.1:PORT
    auth.ts                              ← read/write connection file
    skills/                              ← bundled markdown recipes (embedded at build time)

@slatesvideo/mcp-server
    server.ts                            ← stdio server, registers operations as MCP tools

@slatesvideo/cli
    src/index.ts                         ← commander entry
    src/commands/login.ts                ← magic-link polling
    src/commands/op.ts                   ← `slates run <op>` dispatcher
    src/commands/install-skills.ts       ← installs portable skills for Claude Code and Codex
```

Operations choose their transport internally. `slates_get_credit_balance` hits the cloud. `slates_create_project` hits the desktop. `slates_generate_image` hits the cloud, then the desktop client writes the resulting asset to the local project folder. The user watches it appear in the Slates UI as it lands.

## Publishing

Publish order matters: `@slatesvideo/shared` must land before `@slatesvideo/mcp-server` and `@slatesvideo/cli` (both depend on it at an exact version). Always publish from the repo root with:

```bash
npm run publish:all
```

This builds everything first, then publishes shared → mcp → cli with `--access public`. Each package also has a `prepublishOnly` build hook, so a stray `npm publish` from a fresh clone can't ship an empty `dist`.

## Privacy + security

- The desktop server is bound to `127.0.0.1` only. It rejects any non-loopback connection at the OS level.
- Every request is rejected if it carries a cross-origin `Origin` header (kills browser-fetch attacks) or a non-loopback `Host` header (kills DNS rebinding), before the bearer token is even read.
- The `slates_sk_` token is sent only to the configured cloud host (`slates-api.fly.dev` by default). `SLATES_CLOUD_BASE_URL` can override the host for dev/staging, but only over `https://` (or `http://localhost`) — an insecure override is ignored so the token can't be exfiltrated or sent in cleartext.
- Disconnect (Slates desktop → Settings → AI tools) revokes the `slates_sk_` token server-side and clears it locally. Once revoked, that token's hash never authenticates again — so a leaked copy stops working too.

## License

MIT — see [LICENSE](https://github.com/EricDisero/slates-mcp/blob/HEAD/LICENSE). Copyright Blueprint Online Learning Inc.

### Context on demand

The server lists every tool, and the list stays the same for the whole connection. Your client
decides how much of it to load: Claude Code and Codex send the model the tool names only and fetch a
tool's full definition when it is needed. `slates_load_tools` with `query` finds a tool by task.
Legacy `--tools=compact` and `--tools=flat` launch flags are accepted; both expose the full fixed list.

`slates_get_prompting_guide` with no topic discovers guides from a brief in `query`, or lists the
catalog without a query. With a topic it returns a short card by default. Use `query` for a section or
cinematic technique ID, `depth: "index"` for headings, or `depth: "full"` for the complete guide.
Both text and structured content include the actual guide body. No extra loading hook is required.