scrivener-mcp

A local MCP server that exposes your Scrivener projects to Claude (or any MCP-compatible client). Create new projects from scratch, navigate the binder, read and write document content, and update metadata — all without opening Scrivener.

Requirements

• Node.js 18 or later

• Scrivener 3 on macOS (.scriv packages)

Setup

cd scrivener-mcp
npm install

Environment variables

At least one of SCRIV_DIR or SCRIV_PATH must be set. Both can be set simultaneously.

Running manually

# Multi-project mode (recommended)
SCRIV_DIR="/path/to/ScrivenerProjects" npm start

# Single-project mode
SCRIV_PATH="/path/to/MyProject.scriv" npm start

Configuring Claude Desktop

Edit the Claude Desktop config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Mac:

{
  "mcpServers": {
    "scrivener": {
      "command": "node",
      "args": ["/absolute/path/to/scrivener-mcp/src/index.js"],
      "env": {
        "SCRIV_DIR": "/Users/you/Writing/ScrivenerProjects"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "scrivener": {
      "command": "node",
      "args": ["C:\\path\\to\\scrivener-mcp\\src\\index.js"],
      "env": {
        "SCRIV_DIR": "C:\\Users\\you\\Documents\\ScrivenerProjects",
        "SCRIV_PLATFORM": "windows"
      }
    }
  }
}

Restart Claude Desktop after saving.

Available tools

Project management

Document tools (require an open project)

Creating a project

create_project accepts a full binder structure so Claude can scaffold an entire project from an idea in one call.

Parameters

Binder item structure

{
  "title": "Chapter 1",
  "type": "Folder",
  "synopsis": "Alice finds the letter and confronts Bob.",
  "content": "Optional initial body text (Text items only).",
  "label": "POV: Alice",
  "status": "To Do",
  "includeInCompile": true,
  "children": [...]
}

• type: "Folder" for containers (acts, parts, chapters); "Text" for documents (scenes, notes). Defaults to "Text".

• synopsis: The virtual index card text — appears in Scrivener's corkboard and outliner views. Write a 1–3 sentence summary of what happens or what this item covers.

• label and status must match names defined in the project's labels and statuses arrays.

Example

{
  "name": "My Novel",
  "labels": [
    { "name": "POV: Alice", "color": "blue" },
    { "name": "POV: Bob", "color": "red" }
  ],
  "statuses": ["To Do", "First Draft", "Revised", "Done"],
  "manuscript": [
    {
      "title": "Act One",
      "type": "Folder",
      "synopsis": "Alice discovers the conspiracy.",
      "children": [
        {
          "title": "Chapter 1",
          "type": "Folder",
          "synopsis": "A normal Tuesday turns strange.",
          "children": [
            {
              "title": "The Letter",
              "type": "Text",
              "synopsis": "Alice finds an unsigned letter in her mailbox.",
              "label": "POV: Alice",
              "status": "To Do"
            }
          ]
        }
      ]
    }
  ],
  "research": [
    {
      "title": "Characters",
      "type": "Folder",
      "children": [
        {
          "title": "Alice",
          "type": "Text",
          "synopsis": "Protagonist. Mid-30s journalist, sceptical but curious."
        }
      ]
    }
  ]
}

Collaborative workflow

The intended pattern is to work with Claude on the structure and content of a project together, using Scrivener's own organisational features:

1. Start with get_outline — Claude reads the full nested structure with synopses before suggesting or making any changes. This is how it understands the story shape.

2. Build structure with add_document — Add scenes, chapters, acts, or research notes at any point in the hierarchy. Always include a synopsis; it is what appears on the index card in Scrivener's corkboard.

3. Reorganise with move_document — Move items between parents to restructure the narrative without losing any content or metadata.

4. Write prose with write_document — Once structure is agreed, populate scenes with content.

5. Track progress with update_metadata — Update labels (e.g. POV, scene type) and statuses (e.g. First Draft, Revised) as work progresses.

Notes

• Close Scrivener before writing. write_document, update_metadata, add_document, and move_document modify project files directly. The server detects an open Scrivener instance via the Files/user.lock file Scrivener creates and refuses to write while it exists, so concurrent edits won't silently corrupt the project. Close Scrivener and retry.

• Mutations re-read state automatically. Each mutating call reloads the .scrivx from disk before writing, so external edits made between MCP calls aren't overwritten.

• binder.autosave is kept in sync. Every binder write also refreshes Files/binder.autosave (the zipped snapshot Scrivener cross-references on launch). Without this, Scrivener can decide the on-disk binder is "newer than expected" and shunt MCP-added items into a "Recovered Files" folder.

• write_document generates minimal RTF compatible with Scrivener 3. Non-ASCII characters are Unicode-escaped.

• Label and status IDs are discoverable via list_documents — labelId/statusId are raw IDs, label/status are the resolved names.