MCP Server Documentation

Model Context Protocol (MCP) is an open standard that allows AI assistants to interact directly with external tools and data sources. The Cinematic Blueprint MCP server enables AI assistants like Claude, Windsurf Cascade, and others to read and modify your storyboards programmatically.

Why Use the MCP Server?

Without MCP

Export your storyboard as JSON
Ask AI to analyze or suggest changes
Manually apply changes back
Re-import the modified file

With MCP ✓

Ask AI: "Add a beat to Act II"
AI directly creates the beat
Changes appear immediately
Done!

The MCP server eliminates the export/import cycle and lets you collaborate with AI in real-time on your storyboard.

Capabilities

Read Operations

Resource	Description
`storyboard://current`	Complete storyboard data
`storyboard://acts`	All acts and structure
`storyboard://beats`	All story beat cards
`storyboard://shots`	All storyboard shots

Write Operations

Tool	Description
`add_beat`	Create a new story beat
`edit_beat`	Modify title, description, status
`delete_beat`	Remove a beat
`move_beat`	Move beat to different act
`add_shot`	Add a storyboard shot
`edit_shot`	Modify shot details
`delete_shot`	Remove a shot
`reorder_shots`	Change shot sequence
`add_act`	Create a new act
`import_markdown`	Parse markdown into beats
`export_storyboard`	Export to JSON/markdown

Installation

The MCP server requires Node.js 18+.

cd cinematic-blueprint-mcp
npm install
npm run build

Configuration

Windsurf / Cascade

Go to Settings → MCP Servers and add:

{
  "mcpServers": {
    "cinematic-blueprint": {
      "command": "node",
      "args": ["C:/path/to/cinematic-blueprint-mcp/dist/index.js"],
      "env": {
        "STORYBOARD_PATH": "C:/path/to/your/storyboard.json"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cinematic-blueprint": {
      "command": "node",
      "args": ["C:/path/to/cinematic-blueprint-mcp/dist/index.js"],
      "env": {
        "STORYBOARD_PATH": "C:/path/to/your/storyboard.json"
      }
    }
  }
}

Example Interactions

Adding Story Beats

You: "Add a new beat called 'The Dark Night of the Soul' to Act II"

add_beat({
  "title": "The Dark Night of the Soul",
  "act": "act-2",
  "status": "draft"
})

Importing from Markdown

You: "Import this outline into my storyboard..."

import_markdown({
  "markdown": "# Act I\n## Opening Image\nThe world before..."
})

Editing Shots

You: "Change shot 3 to a close-up with 2 second duration"

edit_shot({
  "id": "shot-3",
  "camera": "CU",
  "duration": "2s"
})

Use Cases

Story Development — Brainstorm beats with AI, restructure acts, generate descriptions
Pre-Production — Plan shots, calculate runtime, generate shot lists
Collaboration — AI reads your structure and suggests improvements

Security

Only accesses the storyboard file you specify
No network requests made by the server
All data stays local on your machine
Runs as a subprocess of your AI client

Troubleshooting

Issue	Solution
Server not connecting	Verify path to `dist/index.js` is correct
Changes not appearing	Reload storyboard in Cinematic Blueprint
"Tool not found" errors	Restart AI client after config changes