# Twine Mcp

> Unofficial MCP server for Twine

- **Type:** MCP server
- **Install:** `agentstack add mcp-unveil-gg-twine-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Unveil-gg](https://agentstack.voostack.com/s/unveil-gg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Unveil-gg](https://github.com/Unveil-gg)
- **Source:** https://github.com/Unveil-gg/twine-mcp

## Install

```sh
agentstack add mcp-unveil-gg-twine-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Twine MCP

MCP server for AI-assisted [Twine](https://twinery.org/) 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

```bash
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.):

```json
{
  "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](DEVELOPMENT.md#workspace-roots) for details.

---

## Tools

| Category | Tools |
|----------|-------|
| **Stories** | `list_stories`, `get_story`, `create_story`, `delete_story`, `export_twee` |
| **Passages** | `list_passages`, `get_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:** `twine://stories`, `twine://story/{name}`, `twine://story/{name}/graph`, `twine://story/{name}/summary`

### Building & bundling assets

`build_story` compiles with the [Tweego](https://www.motoslave.net/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](https://github.com/tmedwards/tweego/issues/30)). 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](CONTRIBUTORS.md)** — local setup, how to help, AI usage policy
- **[DEVELOPMENT.md](DEVELOPMENT.md)** — release workflow, npm auth, CI

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Unveil-gg](https://github.com/Unveil-gg)
- **Source:** [Unveil-gg/twine-mcp](https://github.com/Unveil-gg/twine-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-unveil-gg-twine-mcp
- Seller: https://agentstack.voostack.com/s/unveil-gg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.