# 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

```bash
cd scrivener-mcp
npm install
```

---

## Environment variables

| Variable | Description |
|---|---|
| `SCRIV_DIR` | Path to a directory containing `.scriv` packages. Enables `list_projects`, `open_project`, and `create_project`. |
| `SCRIV_PATH` | Path to a single `.scriv` package. Opens it immediately on startup. |
| `SCRIV_PLATFORM` | `mac` (default) or `windows`. Controls the RTF format used when writing document content. |

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

---

## Running manually

```bash
# 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:**
```json
{
  "mcpServers": {
    "scrivener": {
      "command": "node",
      "args": ["/absolute/path/to/scrivener-mcp/src/index.js"],
      "env": {
        "SCRIV_DIR": "/Users/you/Writing/ScrivenerProjects"
      }
    }
  }
}
```

**Windows:**
```json
{
  "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

| Tool | Description |
|---|---|
| `list_projects` | Lists all `.scriv` packages in `SCRIV_DIR`. |
| `open_project(name)` | Opens a project by name, making it active for all document tools. |
| `create_project(name, ...)` | Creates a new project and opens it. See below. |

### Document tools (require an open project)

| Tool | Description |
|---|---|
| `get_outline(rootUuid?, includeContent?)` | Returns the binder as a nested tree with synopses, labels, and statuses. Pass `rootUuid` to scope to a subtree, and `includeContent: true` to inline prose directly into the tree (one call instead of many `get_document` calls). The best starting point for understanding and working on a project's structure. |
| `list_documents` | Returns the binder as a flat list with depth indicators. Useful for getting UUIDs. |
| `get_document(uuid)` | Returns metadata and plain text content for a single document. |
| `get_documents(uuids)` | Batch version of `get_document` — returns metadata and content for many documents in a single call. |
| `add_document(...)` | Adds a new document or folder to the binder. |
| `move_document(uuid, newParentUuid)` | Moves a binder item to a different parent folder. |
| `write_document(uuid, content)` | Writes new plain text content to a document (stored as RTF). |
| `update_metadata(uuid, changes)` | Updates title, synopsis, label, status, or compile inclusion. |
| `batch_update_metadata(updates)` | Batch version of `update_metadata` — applies many changes in a single `.scrivx` write. |
| `search_documents(query)` | Searches titles and synopses across the binder. |

---

## Creating a project

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

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `name` | string | Project name (becomes the `.scriv` package name). |
| `labels` | array | Label definitions. Each is a string or `{name, color}`. Colors: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `cyan`. |
| `statuses` | array | Status names. Defaults to: To Do, In Progress, First Draft, Revised Draft, Done. |
| `manuscript` | array | Binder items in the Draft (Manuscript) folder. |
| `research` | array | Binder items in the Research folder. |

### Binder item structure

```json
{
  "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

```json
{
  "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.