Skip to main content
Glama

kinoscripter-mcp

Let your own agent write with you in Kinoscripter, the audio-visual script editor on parker.mov.

Kinoscripter has no AI of its own and never asks for a key. Instead, this small local MCP server gives the agent you already use (Claude, Cursor, Hermes, or any client that can launch a command) tools to read and edit your scripts. They're plain .kinoscript.json files in one folder on your computer.

  • Local only. It talks to your agent over stdio and reads and writes the one folder you give it. No network, no telemetry, no accounts.

  • No dependencies. One file of server code plus the editor's own script operations (lib/kinoscript.js). Read it all before you run it; that's the point of this repo.

  • Safe writes. It never writes an invalid script, never writes outside its folder (symlinks included), writes atomically, and with ifUpdatedAt it refuses to overwrite a file that changed since the agent read it.

Needs Node 18.17 or newer.

Set up

1. Add the server to your agent, pointing at a folder for your scripts (it's created if missing).

Claude Code:

claude mcp add kinoscripter -- npx -y github:ParkerGibbons/kinoscripter-mcp ~/Kinoscripts

Any client with an mcpServers config (Claude Desktop, Cursor, …):

{
	"mcpServers": {
		"kinoscripter": {
			"command": "npx",
			"args": ["-y", "github:ParkerGibbons/kinoscripter-mcp", "/Users/you/Kinoscripts"]
		}
	}
}

Prefer not to run code from the network each time? Clone this repo and point your agent at it: "command": "node", "args": ["/path/to/kinoscripter-mcp/server.mjs", "/Users/you/Kinoscripts"].

2. Open the same folder in Kinoscripter. In the editor choose actions → open folder… (Chrome or Edge). The agent's edits appear in the open script as they land, and yours save back to the files as you type. Other browsers: export your script into the folder, and import what the agent writes.

3. Ask. "List my kinoscripts." "Read the cold open and tighten the VO." "Add a scene after the interview: a slow push on the empty workshop, room tone and a single tool clink."

Related MCP server: a0

Tools

Tool

Does

list_scripts

scripts in the folder, with acts / scenes / beats

read_script

the script as text with scene and beat ids (or outline / raw json)

create_script

a new file: one act, one scene, one empty beat (never overwrites)

insert_beat

a beat (VIDEO + AUDIO) after a beat, at the end of a scene, or at the end

edit_beat

replace a beat's VIDEO and/or AUDIO

insert_scene / insert_act

structure, renumbered like the editor does

validate_script

check a file against the editor's structure rules

Text goes in as plain lines with a little markdown (# headings, - bullets, > quotes, **bold**, *italic*).

Limits, honestly

  • One person and their agent, not multi-user collaboration. Two writers racing the same file can still lose an edit between a read and a write; ifUpdatedAt narrows that, it doesn't remove it.

  • The folder is yours and trusted: the server isn't a sandbox against other programs on your machine.

  • Live folder sync uses the File System Access API, so Chrome and Edge only for now.

Develop

node server.mjs ~/Kinoscripts      # or KINOSCRIPTER_DIR=~/Kinoscripts node server.mjs
npm test                           # drives the server over stdio

This repo is exported from parker.mov's source, where the editor and the server share lib/kinoscript.js. Issues and ideas are welcome here.

MIT licensed.

Available Tools

8 tools
create_scriptA

Create a new script file (one act, one scene, one empty beat). Never overwrites.

Inputs: title (required), file, synopsis.

edit_beatC

Replace the video and/or audio of a beat. Plain text; one line per paragraph. A little markdown is kept: "# " headings, "- " bullets, "> " quotes, bold, italic.

Inputs: file (required), beatId (required), audio, video, +1 more.

insert_actA

Add an act (with one scene and one beat) at the end, or after act N (1-based).

Inputs: file (required), heading, afterAct, ifUpdatedAt, +1 more.

insert_beatA

Add a beat (one moment: what we see beside what we hear). Goes after afterBeatId, else at the end of sceneId, else at the end of the script. Plain text; one line per paragraph. A little markdown is kept: "# " headings, "- " bullets, "> " quotes, bold, italic.

Inputs: file (required), audio, video, sceneId, +2 more.

insert_sceneB

Add a scene (with one beat) after afterSceneId, else at the end of act N (1-based), else at the end.

Inputs: file (required), act, audio, video, +3 more.

list_scriptsA

List the Kinoscripter scripts in the folder with their size (acts, scenes, beats).

Inputs: no named parameters.

read_scriptA

Read a script. format "text" (default) is the whole script with act/scene/beat ids to quote in edits; "outline" is the same as JSON; "json" is the raw editor document.

Inputs: file (required), format.

validate_scriptA

Check a script file against the editor's structure rules. Lists every problem with its path.

Inputs: file (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing/reading/creating scripts, inserting beats/scenes/acts, editing beats, and validating structure. The insert versus edit distinction is clear, and hierarchical inserts are separated by structural level.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: list_scripts, read_script, create_script, insert_beat, edit_beat, insert_scene, insert_act, validate_script. There are no mixed conventions or vague standalone verbs.

    Tool Count5/5

    Eight tools is well-scoped for a script-editing server with acts, scenes, and beats. Each tool maps to a meaningful operation without obvious redundancy or unnecessary surface area.

    Completeness3/5

    The core workflow of creating, reading, inserting, editing beats, and validating is covered, but there are no delete/remove operations for scripts, acts, scenes, or beats. Scene/act editing and reordering/moving are also absent, leaving notable lifecycle gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to inspect and carefully edit a bounded local workspace via stdio, with a read-only default, conflict-safe updates, and no network listener or telemetry.
      10
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to open, edit, check, run, emit, and save source programs through structured, revision-checked tools over stdio, confining paths to the launch root and returning diagnostics with fixes for rejected edits.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives MCP-capable agents read and write access to a SilverBullet space, letting them list, read, create, overwrite, append to, delete, and substring-search markdown pages. It forwards tool calls to SilverBullet's built-in /.fs HTTP API over either stdio or token-gated streamable HTTP, with no changes needed inside SilverBullet itself.
      37 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude and other AI agents to work directly in a local-first planning vault stored as plain JSON files, so they can read and edit kanban boards, plans, notes and decisions alongside the user. Every change made by an agent is recorded in history and can be undone.
      1
      MIT