Skip to main content
Glama

TypeWriter MCP

MCP server for the Typewriter Minecraft plugin. It lets AI assistants in Cursor, Claude Desktop, and other MCP clients read and edit storylines: pages, dialogues, facts, triggers, and the rest of the entry graph.

You can work live against a running server over websocket, or edit page JSON files offline.

What it does

Typewriter stores story content as pages and entries. The web editor is fine for manual work, but slow when you want an agent to draft whole branches, fix dialogue, or wire up triggers across dozens of entries. This server exposes that data as MCP tools so the assistant can do the editing for you.

In socket mode it uses the same protocol as the official web editor. Changes land in staging first, show up in the panel, and can be published to production without clobbering work you have open elsewhere.

Related MCP server: mc-mcp-server

Modes

Socket (recommended for live servers)

Connect to the running plugin over websocket. Best for production and any setup where you want changes visible in the web panel before they go live.

File (offline)

Edit plugins/Typewriter/pages/*.json directly. Useful when the server is down or you want to batch-edit files and reload later. Run /typewriter reload on the server after saving.

Install

git clone https://github.com/yurchik228336/TypeWriter-MCP.git
cd TypeWriter-MCP
npm install
npm run build

Requires Node.js 18+.

Cursor / Claude Desktop config

Add this to your MCP config (for Cursor: ~/.cursor/mcp.json):

{
  "mcpServers": {
    "typewriter": {
      "command": "node",
      "args": ["C:/path/to/TypeWriter-MCP/dist/index.js"],
      "env": {
        "TYPEWRITER_MODE": "socket",
        "TYPEWRITER_URL_FILE": "C:/path/to/TypeWriter-MCP/.typewriter-session-url"
      }
    }
  }
}

With this setup the server starts in socket mode and waits for a connect URL. When you want to work live, run /typewriter connect in-game and paste the full link into chat. The agent calls connect_live and keeps the socket open for the rest of the session. You do not need to paste the link again while that connection is still alive.

If you prefer a fixed URL in config instead:

"env": {
  "TYPEWRITER_MODE": "socket",
  "TYPEWRITER_URL": "http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>"
}

Note: with auth: session, that token expires when the player who generated it logs out.

File mode:

"env": {
  "TYPEWRITER_MODE": "file",
  "TYPEWRITER_PAGES_DIR": "C:/server/plugins/Typewriter/pages"
}

Typewriter plugin setup (socket)

  1. Enable websocket in plugins/Typewriter/config.yml:

enabled: true
websocket:
  port: 9092
  auth: session

Restart the server after editing the config.

  1. In-game, run /typewriter connect. You get a URL like:

http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>
  1. Paste that URL to your agent or set it in TYPEWRITER_URL.

Plain websocket URLs work too: ws://host:9092?token=<uuid>

For a trusted local network you can set auth: none and skip tokens. Only do that if you know what you are exposing.

Typical agent workflow

  1. Paste the connect URL when starting a live session.

  2. list_pages / read_page to see what exists.

  3. create_page, add_entry, connect_entries to build or extend the story.

  4. validate_storyline to catch broken trigger references.

  5. publish to apply staging changes in-game (socket mode only).

If the session drops or the token expires, send a fresh connect URL.

Example prompts

Paste these into Cursor or Claude Desktop when the Typewriter MCP is connected. For live work, include your connect URL in the first message.

Connect and inspect

Here is my Typewriter connect URL: http://host:8080/#/connect?host=1.2.3.4&port=9092&token=...
Connect to the server and list all pages. Tell me what storylines already exist.
Read the page named "chapter1" and summarize every dialogue entry and how the triggers are wired.

Create a new storyline

Connect with this URL: ...
Create a static page called "village_npcs" with a simple_speaker entry for a villager named Mira.
Then create a sequence page called "village_intro" with a spoken_dialogue where Mira greets the player.
Wire the dialogue flow with connect_entries and run validate_storyline when you are done.
Publish the changes.
Add a new option_dialogue to page "chapter2" with two choices:
1) "I'll help you" -> sets a permanent_fact "agreed_to_help"
2) "Not now" -> ends the conversation
Link the options to the correct follow-up entries.

Edit existing content

Search all pages for the text "old quest name" and update every matching dialogue line to "new quest name".
Do not change entry ids or trigger links.
On page "main_quest", find the entry where the blacksmith speaks and change his line to:
"We need iron from the mines. Bring me ten ingots and I'll pay you well."

Debug and validate

Run validate_storyline across the whole project and fix any broken trigger references you can resolve without guessing missing entries.
Show me what you changed.
Search for entries that reference fact id "abc123" and list which pages use it.

File mode (offline)

Using file mode, read everything under plugins/Typewriter/pages.
Create a new sequence page "side_quest_rat" with three spoken_dialogue entries: start, middle, reward.
Save the files. I will run /typewriter reload on the server myself.

Tools

Tool

Description

connection_status

Current mode, connection state, saved URL

connect_live

Connect using a /typewriter connect URL

list_pages

List pages (id, name, type, entry count)

read_page

Read a full page by name or id

create_page

Create a page (sequence, static, cinematic, manifest)

rename_page

Rename a page

delete_page

Delete a page and all its entries

add_entry

Add an entry (dialogue, speaker, fact, etc.)

update_entry

Update one field by dotted path (text, speaker, criteria.0.value)

replace_entry

Replace an entry, keeping the same id

delete_entry

Delete an entry by id

connect_entries

Append a trigger link between two entries

search_entries

Full-text search across all pages

validate_storyline

Find broken references in triggers / triggeredBy

publish

Publish staging to production (socket mode only)

Environment variables

Variable

Default

Description

TYPEWRITER_MODE

socket

socket or file

TYPEWRITER_URL

—

Optional fixed connect URL

TYPEWRITER_URL_FILE

.typewriter-session-url in cwd

Where the last connect URL is stored

TYPEWRITER_PAGES_DIR

plugins/Typewriter/pages

Pages directory for file mode

License

MIT. Use it however you want: personal projects, servers, forks, commercial work, no permission needed. See LICENSE.

Not affiliated

This is an unofficial community tool. Typewriter is developed by its own team; this MCP just speaks their websocket and file formats.

Available Tools

15 tools
add_entryA

Add an entry to a page. fields = raw Typewriter entry JSON (needs 'name' and 'type'; id is generated). Common types: spoken_dialogue, option_dialogue, simple_speaker, permanent_fact.

Inputs: page (required), fields (required).

connect_entriesA

Wire story flow: append 'toEntryId' to the 'triggers' list of 'fromEntryId'.

Inputs: fromPage (required), toEntryId (required), fromEntryId (required).

connection_statusA

Show current Typewriter connection status and whether a saved connect URL exists.

Inputs: no named parameters.

connect_liveB

Connect to a live Typewriter websocket using the full URL from /typewriter connect.

Inputs: url (required), forceReconnect.

create_pageB

Create a new page. Types: sequence, static, cinematic, manifest.

Inputs: name (required), type (required), chapter, priority.

delete_entryC

Delete an entry by id.

Inputs: page (required), entryId (required).

delete_pageB

Delete a page and all its entries.

Inputs: page (required).

list_pagesA

List all pages (name, id, type, entry count).

Inputs: no named parameters.

publishA

Publish staging changes to production (applies edits live in-game).

Inputs: no named parameters.

read_pageA

Read a full page (all entries) by page name or id.

Inputs: page (required).

rename_pageC

Rename a page.

Inputs: page (required), newName (required).

replace_entryB

Replace a whole entry with a new object (must keep the same id).

Inputs: page (required), entry (required).

search_entriesB

Full-text search across all pages/entries.

Inputs: query (required).

update_entryB

Update a single field of an entry by dotted path (e.g. 'text', 'speaker', 'criteria.0.value').

Inputs: page (required), path (required), entryId (required), value.

validate_storylineB

Find broken references (triggers/triggeredBy pointing to missing ids).

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: pages vs entries vs connection vs publish. Update_entry and replace_entry are clearly differentiated by scope (field-level vs whole object). Even connect_live and connection_status are distinct (action vs status check).

    Naming Consistency4/5

    Most tools follow verb_noun snake_case (list_pages, create_page, add_entry, delete_entry). Minor deviations: 'connection_status' (noun phrase), 'connect_live' (verb+adverb), and 'publish' (single verb) break the pattern slightly, but the style remains consistent and readable.

    Tool Count5/5

    15 tools provide a well-scoped set covering connection, page management, entry management, story wiring, search, validation, and publishing. No redundancy or bloat; each tool serves a clear purpose in the narrative authoring workflow.

    Completeness4/5

    The surface covers the full lifecycle for pages and entries, plus important cross-cutting concerns (search, validation, publish). Minor gaps exist (no update_page for metadata, no remove_trigger operation), but agents can work around these using existing tools without major friction.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI-driven interactions with Minecraft through a WebSocket-based server and MCP protocol, allowing external MCP clients and in-game chat to trigger AI tools.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A locally-run MCP server that connects to Twine's story library, enabling AI-assisted story management, passage editing, link-graph analysis, and narrative intelligence from any MCP-compatible client.
      63 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for managing and playing a running SillyTavern instance, enabling AI coding assistants to read/write character cards, worldbooks, and chats, and to interact as a player via the full generation pipeline.
      35
      MIT