Skip to main content
Glama

Storywright MCP

Multi-agent book-writing MCP server for Cursor, Claude Desktop, OpenCode, or any host that speaks MCP over stdio. It combines a guarded chapter pipeline (writer → editor → configurable third passes → approve), JSON/Markdown projects on disk, book-bible planning, continuity tracking, manuscript search, marker scans, prior-chapter context budgeting, and export/diff helpers.

Golden path (first hour)

  1. Install (from this repo):

    cd C:\Apps\claude_plugins\storywright-mcp
    uv sync --extra dev
  2. Set API key (User env or MCP env block):

    • ANTHROPIC_API_KEY and/or ANTHROPIC_AUTH_TOKEN — required for writer/editor/third-pass (MiniMax usually uses Bearer + ANTHROPIC_BASE_URL).

  3. Register MCP in Cursor — create or edit mcp.json:

    Scope

    Path (Windows)

    User (all workspaces)

    %USERPROFILE%\.cursor\mcp.json

    This repo only

    <repo>\.cursor\mcp.json

    Merge storywright into the existing "mcpServers" object if the file already has other servers.

    Anthropic API key (secrets via Windows env — set User env vars, then reference them):

    {
      "mcpServers": {
        "storywright": {
          "command": "uv",
          "args": ["run", "--directory", "C:/Apps/claude_plugins/storywright-mcp", "storywright-mcp"],
          "env": {
            "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
            "STORYWRIGHT_PROJECTS_ROOT": "C:/Users/you/Documents/writing",
            "STORYWRIGHT_ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
          }
        }
      }
    }

    MiniMax (same as your working shell — Bearer + base URL + model):

    {
      "mcpServers": {
        "storywright": {
          "command": "uv",
          "args": ["run", "--directory", "C:/Apps/claude_plugins/storywright-mcp", "storywright-mcp"],
          "env": {
            "ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
            "ANTHROPIC_AUTH_TOKEN": "${env:ANTHROPIC_AUTH_TOKEN}",
            "STORYWRIGHT_ANTHROPIC_MODEL": "MiniMax-M2.7",
            "STORYWRIGHT_PROJECTS_ROOT": "C:/Users/you/Documents/writing"
          }
        }
      }
    }

    Set ANTHROPIC_AUTH_TOKEN in Windows Environment Variables (User), or temporarily embed the value only if you accept the risk of it sitting on disk. Edit STORYWRIGHT_PROJECTS_ROOT to wherever you want book_projects/ to live.

    Reload MCP: Command Palette → “Cursor: Reload MCP Servers” (or restart Cursor). uv must be on PATH for the terminal where Cursor spawns servers.

  4. In chat, run tools in order:

    • check_environment — confirms key + model + version.

    • create_book_project(project_name="my-novel", book_title="My Novel", third_agents=["comedy","pacing"])

    • plan_book() … through phases (optional), or skip to chapters.

    • add_chapter / add_character as needed.

    • get_pipeline_status — shows exact next tool per chapter.

    • Per chapter: start_chapter → run_writer_agent → run_editor_review → each run_third_agent → approve_chapter.

  5. Artifacts to know:

    • briefs/revision_queue.json — notes from request_revision (writer prompt reads these).

    • reports/chapter-NN-editor-meta.json — parsed verdict + meta block from editor.

    • manuscript/chapter-NN-draft.prev.md — backup before each writer overwrite; use diff_chapter.

    • EXPORT-manuscript.md — optional output from export_manuscript.

Related MCP server: Nyxdoc

Features

  • Strict workflow: Third-pass only after editor; approve requires all configured third-pass agents unless force=true.

  • Pipeline hints: get_pipeline_status lists the next tool call per chapter.

  • API readiness: check_environment validates Anthropic credentials (ANTHROPIC_API_KEY and/or ANTHROPIC_AUTH_TOKEN) before you burn a session.

  • Prior prose budget: Writer includes recent approved chapter text up to configurable word/chapter limits (saves context vs dumping the whole book).

  • Retries: Transient Anthropic errors (429/5xx, timeouts) retry with backoff (STORYWRIGHT_ANTHROPIC_MAX_RETRIES).

  • Structured editor meta: Editor reports should end with ---STORYWRIGHT_META_START--- … END---; parsed JSON beside the markdown report.

  • Export / diff: export_manuscript, diff_chapter (draft vs .prev.md).

  • Resources: storywright://project/*, storywright://meta/version.

Install

cd storywright-mcp
uv sync --extra dev

Environment

Variable

Purpose

ANTHROPIC_API_KEY

Optional if using Bearer below — writer/editor/third-pass calls

ANTHROPIC_AUTH_TOKEN

Optional — Bearer token (same pattern as Claude Code; MiniMax often uses this instead of API_KEY)

ANTHROPIC_BASE_URL

Optional — e.g. https://api.minimax.io/anthropic for MiniMax’s Anthropic-compatible API

STORYWRIGHT_ANTHROPIC_MODEL

Model id (e.g. MiniMax-M2.7 when using MiniMax)

STORYWRIGHT_PROJECTS_ROOT

Parent directory; projects go to {root}/book_projects/<slug>/

STORYWRIGHT_STATE_DIR

last_project.json for load_last_book_project (default ~/.storywright)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_WORDS

Max words of prior approved prose injected into writer (~default 12000)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_COUNT

Max number of prior chapters considered (~default 8)

STORYWRIGHT_ANTHROPIC_MAX_RETRIES

Retries for transient API failures (~default 2)

STORYWRIGHT_ANTHROPIC_RETRY_DELAY_SECONDS

Base delay between retries (~default 2.0)

MiniMax (Anthropic-compatible gateway)

Storywright uses the official anthropic Python SDK, which reads ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN the same way as Claude Code. Mirror your ~/.claude/settings.json env into the Storywright MCP env block in Cursor (or shell), for example:

  • ANTHROPIC_BASE_URL = https://api.minimax.io/anthropic

  • ANTHROPIC_AUTH_TOKEN = your MiniMax token (Bearer)

  • STORYWRIGHT_ANTHROPIC_MODEL = MiniMax-M2.7 (or whatever model id your provider expects)

Do not commit API keys; prefer OS env or Cursor secrets.

Run (stdio)

uv run storywright-mcp
uv run python -m storywright_mcp

Claude Desktop / OpenCode

Use the same command / args as Cursor if your app supports MCP stdio servers.

Typical workflow

  1. create_book_project(..., third_agents=[...]) or load_book_project("C:/absolute/.../book_projects/my-book")

  2. plan_book() … (optional)

  3. start_chapter(1) → run_writer_agent(1) → run_editor_review(1) → run_third_agent(1, …) → approve_chapter(1)

Use get_pipeline_status whenever you lose track.

CLI

uv run storywright-mcp agents           # list third-pass agents
uv run storywright-mcp smoke             # ping Anthropic/MiniMax (tiny token use)
uv run storywright-mcp smoke --with-book # temp folder + new project + chapter 1 writer (full pipeline chunk)

Names like run_editor_review(1) are MCP tools (used from Cursor/chat), not shell commands. From PowerShell you can call the same logic after load_book_project:

uv run python -c "from storywright_mcp import workflow; workflow.load_book_project(r'C:/path/to/book_projects/your-book'); print(workflow.run_editor_review(1))"

Test MiniMax (or any Anthropic-compatible proxy)

From PowerShell, set the same variables as in ~/.claude/settings.json, then run smoke from the repo (credentials stay in your shell only):

$env:ANTHROPIC_BASE_URL = "https://api.minimax.io/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<your-token>"
$env:STORYWRIGHT_ANTHROPIC_MODEL = "MiniMax-M2.7"
cd C:\Apps\claude_plugins\storywright-mcp
uv run storywright-mcp smoke

If you see STORYWRIGHT_SMOKE_OK in the output, routing and auth work. Use smoke --with-book to confirm create_book_project → run_writer_agent against live inference (costs more tokens; files land under a temp storywright-smoke-* directory).

CI

GitHub Actions runs ruff + pytest on push/PR (.github/workflows/ci.yml).

License

MIT

Available Tools

35 tools
add_chapterC

Register a chapter outline.

Inputs: chapter_num (required), title (required), target_words. Returns: result

add_characterC

Add a character and continuity entry.

Inputs: name (required), role (required), description, voice_notes, +1 more. Returns: result

add_deathC

Schedule a canonical death.

Inputs: character (required), chapter (required), circumstances (required), death_style. Returns: result

add_established_factD

Inputs: fact (required), chapter (required), source. Returns: result

add_inventory_itemD

Track an inventory item.

Inputs: name (required), initial_holder (required), description, acquired_chapter. Returns: result

add_locationD

Inputs: chapter (required), location (required), description. Returns: result

add_running_gagD

Register a running gag.

Inputs: name (required), owner (required), setup_chapter (required), description, +1 more. Returns: result

approve_chapterA

Approve chapter; updates continuity. Requires all configured third passes unless force=true.

Inputs: chapter_num (required), force. Returns: result

check_environmentA

Verify ANTHROPIC_API_KEY and show model / prior-chapter budget / Storywright version.

Inputs: no named parameters. Returns: result

create_book_projectC

Create a new book project under book_projects/ (or STORYWRIGHT_PROJECTS_ROOT). Loads the new project.

Inputs: project_name (required), book_title (required), genre, authors, +2 more. Returns: result

diff_chapterC

Diff current draft vs .prev.md snapshot from last writer overwrite.

Inputs: chapter_num (required), max_lines. Returns: result

export_manuscriptC

Concatenate approved chapters into one markdown file at project root.

Inputs: output_filename. Returns: result

fire_gagD

Inputs: gag_name (required), chapter (required). Returns: result

get_book_bibleD

Readable bible markdown.

Inputs: no named parameters. Returns: result

get_chapter_statusC

Inspect one chapter.

Inputs: chapter_num (required). Returns: result

get_continuity_logC

JSON continuity log.

Inputs: no named parameters. Returns: result

get_inventoryD

Inputs: no named parameters. Returns: result

get_living_charactersD

Inputs: no named parameters. Returns: result

get_pipeline_statusB

Next MCP tool to call per chapter (guarded pipeline hints).

Inputs: no named parameters. Returns: result

get_project_statusB

Markdown table of chapters, statuses, editor verdicts, third-pass completion.

Inputs: no named parameters. Returns: result

get_running_gagsD

Inputs: no named parameters. Returns: result

list_third_agentsA

List built-in third-pass agents.

Inputs: no named parameters. Returns: result

load_book_projectB

Load an existing project from disk (prefer absolute paths).

Inputs: project_path (required). Returns: result

load_last_book_projectA

Load the last successfully opened project from ~/.storywright/last_project.json if valid.

Inputs: no named parameters. Returns: result

mark_character_deadD

Inputs: character_name (required), chapter (required), cause (required). Returns: result

plan_bookC

Phased book bible planning (identity→…→tone); completes with sync to project config.

Inputs: phase, data, reset, status. Returns: result

request_revisionC

Send chapter back to writer with notes.

Inputs: chapter_num (required), notes (required). Returns: result

run_editor_reviewC

Editor pass after writer.

Inputs: chapter_num (required). Returns: result

run_third_agentB

Third-pass reviewer (comedy, pacing, …). Repeat until all project.third_agents covered.

Inputs: chapter_num (required), agent_type. Returns: result

run_writer_agentA

Draft chapter via Claude (DRAW → AWAITING_EDITOR). Requires ANTHROPIC_API_KEY.

Inputs: chapter_num (required), chapter_brief. Returns: result

scan_manuscript_markersA

Find TODO/FIXME/DRAFT/TBD/XXX markers in manuscript markdown.

Inputs: no named parameters. Returns: result

search_manuscriptC

Substring search across manuscript/*.md.

Inputs: query (required), file_glob. Returns: result

start_chapterB

Open drafting for a chapter (NOT_STARTED → DRAFT).

Inputs: chapter_num (required). Returns: result

transfer_itemD

Inputs: item_name (required), new_holder (required), chapter (required). Returns: result

update_planC

Patch book_bible.json; may sync characters/deaths/gags into project.

Inputs: section, changes. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2/5.0

    Scored across 35 tools

    Disambiguation2/5

    Many tool descriptions are blank or minimal (e.g., add_location, fire_gag, get_inventory), and several tools have overlapping purposes (e.g., add_death vs mark_character_dead, add_running_gag vs fire_gag). This makes it difficult for an agent to distinguish between tools.

    Naming Consistency3/5

    Tool names follow a verb_noun pattern but use a wide variety of verbs (add, approve, check, create, diff, export, fire, get, list, load, mark, plan, request, run, scan, search, start, transfer, update). This variety, while not chaotic, lacks a strong consistent theme.

    Tool Count2/5

    35 tools is far above the recommended range of 3-15 for a well-scoped set, and significantly exceeds the 25+ threshold. The high count suggests over-specialization or redundant functionality.

    Completeness3/5

    The tool set covers many aspects of story writing (chapters, characters, inventory, gags, planning, etc.) but lacks basic CRUD operations such as delete or update for most resources, and has redundant tools (e.g., add_death and mark_character_dead). Some obvious gaps in lifecycle management are present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local MCP server for maintaining internal consistency in fiction writing, with constraint-based fact checking, branching, and author-oracle conflict resolution.
      27
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Nyxdoc, a document system where humans and external agents collaborate on documents with version history, agent to-dos, and workspace permissions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that lets multiple AI coding agents share state, preserve context across sessions, and coordinate via a knowledge graph, messaging, and branch-preserving checkpoint/resume with conflict handling.
      76 npm
      1
      Apache 2.0