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
ifUpdatedAtit 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."
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;
ifUpdatedAtnarrows 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.