twine-mcp

MCP server for AI-assisted Twine interactive story authoring. Edits .twee files directly, provides build tooling to output playable HTML, and can export stories for visualization in the Twine GUI.

Works with Cursor, Claude Code, Claude Desktop, and Codex CLI.

Setup

npm install -g @unveil-gg/twine-mcp
twine-mcp setup

The wizard asks for your workspace directory, picks your editor, and writes the MCP config — no manual JSON editing.

Restart your editor when done. Ask your AI to run ping to confirm.

Add to your editor's MCP config (~/.cursor/mcp.json, ~/.claude.json, etc.):

{
  "mcpServers": {
    "twine": {
      "command": "twine-mcp",
      "env": {
        "TWINE_PROJECT": "/Users/yourname/Documents/games"
      }
    }
  }
}

TWINE_PROJECT can point to a single game folder or a workspace containing multiple games. The server discovers all projects automatically, and supports multiple workspace roots at once — including the folder open in your editor. See DEVELOPMENT.md for details.

Related MCP server: nexus-mcp

Tools

MCP Resources: twine://stories, twine://story/{name}, twine://story/{name}/graph, twine://story/{name}/summary

Building & bundling assets

build_story compiles with the Tweego compiler (downloaded and cached on first use). Drop image/audio/video/font files under src/ and they're bundled automatically as embedded passages — no manual base64 step needed:

• src/ — passed to Tweego; anything dropped here (.twee, .css, .js, fonts, images, audio, video) gets compiled or bundled into the output HTML.

• assets/ — left alone by the compiler; use this for files you want to reference by relative URL instead of embedding.

Asset bundling into Twine.image/Twine.audio/Twine.video passages is a SugarCube-specific feature — other formats skip them (see skippedAssets in the build_story response). A file whose name collides with an existing passage is also skipped rather than overwritten.

No prebuilt Tweego binary exists yet for Apple Silicon Macs (an upstream gap). Until twine-mcp ships its own build, run under Rosetta 2 or build Tweego yourself and point TWINE_MCP_TWEEGO_BIN at the binary.

Recommended AI workflow

ping → summarize_story → get_story_context → get_story_branches
     → get_narrative_flow → get_passage_context → get_all_endings

Start cheap (summarize_story ≈ 200 tokens), go deeper only when needed.

Contributing & development

• CONTRIBUTORS.md — local setup, how to help, AI usage policy

• DEVELOPMENT.md — release workflow, npm auth, CI