Skillget

twine-mcp

mcp
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • execSync — Synchronous shell command execution in src/cli/setup.ts
  • os.homedir — User home directory access in src/cli/setup.ts
  • process.env — Environment variable access in src/cli/setup.ts
  • os.homedir — User home directory access in src/config.ts
  • process.env — Environment variable access in src/config.ts
  • os.homedir — User home directory access in src/format-manager.ts
  • network request — Outbound network request in src/format-manager.ts
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Unofficial MCP server for Twine

README.md

Twine MCP logo

Twine MCP

npm versionCIlicenseMCP compatible

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.

Manual config

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.

Tools

Category Tools
Stories list_stories, get_story, create_story, delete_story, export_twee
Passages list_passages, get_passage, patch_passage, create_passage, update_passage, delete_passage, rename_passage, set_start_passage, batch_update
CSS get_stylesheet, update_stylesheet
Graph get_link_graph, find_broken_links, find_dead_ends, find_orphans, find_cycles, get_passage_path, get_reachable_passages
Analysis analyze_story, get_story_stats, search_passages, find_variable_usage, check_tag_consistency
Narrative summarize_story, get_story_context, get_narrative_flow, get_all_endings, get_passage_context, get_story_branches
Project create_project, build_story, validate_story, import_from_twine, export_for_twine, move_passage, list_files
Formats list_story_formats, get_format_info, get_format_syntax_guide
Refactor split_passage, merge_passages
Utility ping, get_config, list_workspace_roots, rescan_workspace

MCP Resources (compact JSON, no passage text, no editor coordinates):

  • twine://stories — story index
  • twine://stories/{name}/manifest — metadata and passage index (name, tags, wordCount, links)
  • twine://stories/{name}/graph — link adjacency list
  • twine://stories/{name}/summary — counts and issue totals

twine://story/{name}, .../graph, and .../summary are aliases of those payloads. The server accepts resources/subscribe and emits notifications/resources/updated when a watched story's source files change.

Prompts: audit_branching_dead_ends, check_narrative_continuity.

get_story returns metadata. include_passages adds a title index, not passage text. export_twee writes export/<story>.twee and returns the path. Local edits should use patch_passage. get_link_graph defaults to link counts; get_narrative_flow and get_all_endings default to previews.

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_passage → patch_passage

Or run the audit_branching_dead_ends prompt. Start cheap (summarize_story or the manifest resource), then read one passage at a time.

Contributing & development

Reviews (0)

No results found