twine-mcp

A locally-run MCP server for Twine interactive story authoring.

Connects to Twine's story library on the file system and exposes tools for story management, passage CRUD, link-graph analysis, plot consistency checking, and AI-optimized narrative intelligence — all callable from Cursor, Claude Desktop, or any MCP-compatible AI client.

Quick start

# Option A: zero-install
npx twine-mcp

# Option B: global install
npm install -g twine-mcp
twine-mcp

# Custom library path
TWINE_LIBRARY="C:/Users/you/Documents/Twine/Stories" npx twine-mcp

The server auto-discovers your Twine story library from:

1. TWINE_LIBRARY environment variable

2. Electron app-prefs.json (reads storyLibraryFolderPath)

3. OS default: ~/Documents/Twine/Stories

Related MCP server: nexus-mcp

Cursor setup

Add to your .cursor/mcp.json (or user-level MCP config):

{
  "mcpServers": {
    "twine": {
      "command": "npx",
      "args": ["twine-mcp"],
      "env": {
        "TWINE_LIBRARY": "C:/Users/yourname/Documents/Twine/Stories"
      }
    }
  }
}

Claude Desktop setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "twine": {
      "command": "npx",
      "args": ["twine-mcp"]
    }
  }
}

Companion format (optional)

The companion format adds a toolbar button to the Twine passage editor showing MCP status and setup instructions.

Install:

1. Open Twine → Story Formats → Add a New Format

2. Enter the path to src/companion-format/format.js as a file:// URL:

   • Windows: file:///C:/Users/you/Documents/Unveil/twine-mcp/twine-mcp/src/companion-format/format.js

   • macOS/Linux: file:///home/you/.../twine-mcp/src/companion-format/format.js

3. Set it as a proofing format on any story to see the MCP indicator

Tool reference

Recommended AI workflow (cheapest → richest)

1. ping                         health check, confirm connection
2. summarize_story              ~200 tokens, orient to story structure
3. get_story_context            configurable bundle with issues list
4. get_story_branches           decision tree overview
5. get_narrative_flow           full prose in DFS order
6. get_passage_context          deep dive on a specific passage
7. get_all_endings              audit every ending path

Story management

Passage CRUD

Graph & navigation

Story analysis

Narrative intelligence (AI-optimized)

Story format awareness

Utility

MCP Resources

Token efficiency conventions

Every tool follows these conventions to minimize token cost:

• fields — select which properties to return (e.g. ["name","tags"])

• compact: true — passage lists return name + 80-char preview only

• max_depth / max_passages — bound traversal output

• Passage text is never included in list/graph tools by default

• get_story_context(fields=["meta","issues"], compact=true) ≈ 200 tokens

How it works

twine-mcp watches ~/Documents/Twine/Stories/*.html with chokidar. Files are parsed using extwee. Writes splice updated <tw-storydata> back into the original HTML — preserving the embedded story format. TwineJS detects file changes on focus and reloads automatically.

Twine has no plugin API or HTTP server — this server operates entirely through the file system. The companion story format adds a cosmetic toolbar button but cannot perform deeper integration.

Development

git clone <repo>
cd twine-mcp
npm install
npm run build        # compile TypeScript
npm start            # run server
npm test             # run tests (vitest)

Scope & limitations

• Desktop/Electron Twine only (v1 — web/PWA localStorage not supported)

• Passage text is treated as opaque source (macros/widgets are not executed)

• Format conversion (Harlowe → SugarCube) is guidance only, not automated

• compile_story produces a proofing HTML; fully playable output requires a story format bundle