TwelveTake-Studios/scrivener-mcp

Scrivener MCP Server

An MCP (Model Context Protocol) server that lets AI assistants read, write, and organize Scrivener projects. Works with Claude, ChatGPT, Gemini, and other MCP-compatible AI tools.

Features

• Read & Write - Full access to manuscript content, notes, and synopses
• Organize - Create, move, rename, and delete documents and folders
• Search - Find content across your entire project with context
• Compile - Export your manuscript to PDF directly from AI
• Continuity Tools - Check character/setting consistency across your manuscript

Perfect for writers who want AI assistance with drafting, revision, outlining, or project organization.

Requirements

• Node.js 18 or higher
• Scrivener 3 (macOS or Windows)
• An MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Cursor, etc.)

Installation

Option 1: npm (Recommended)

npm install -g @twelvetake/scrivener-mcp

Then add to your MCP client's configuration. For Claude Desktop (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "scrivener": {
      "command": "scrivener-mcp"
    }
  }
}

Option 2: From Source

1. Clone and build:

   git clone https://github.com/TwelveTake-Studios/scrivener-mcp.git
   cd scrivener-mcp
   npm install
   npm run build
   

2. Add to your Claude Desktop configuration:

   {
     "mcpServers": {
       "scrivener": {
         "command": "node",
         "args": ["/full/path/to/scrivener-mcp/dist/index.js"]
       }
     }
   }
   

3. Restart Claude Desktop

Quick Start

Once installed, try these commands with your AI assistant:

Open my Scrivener project at /path/to/mynovel.scriv

Show me the structure of my manuscript

Read Chapter 3

Create a new scene called "The Confrontation" in Chapter 5

Compile everything up to Chapter 7 into a PDF

Find all mentions of "Sarah" and check if her descriptions are consistent

Available Tools (22 total)

Project Management

Document Operations

Synopsis & Notes

Search

Compile & Export

Continuity Checking

Tool Reference

open_project

Open a Scrivener project to work with.

Parameters:

• path (required): Path to the .scriv project folder

Example:

Open my project at D:/Writing/MyNovel.scriv

get_structure

View the binder hierarchy of your project.

Parameters:

• folderId (optional): Get structure for specific folder only
• maxDepth (optional): Maximum depth to traverse

Example:

Show me the structure of my manuscript
Show me only what's in Chapter 3

read_document

Read the content of a document.

Parameters:

• documentId (required): UUID of the document
• includeSynopsis (optional): If true, returns both content and synopsis

Example:

Read the content of "Chapter 1 - The Beginning"
Read Chapter 3 with its synopsis

write_document

Replace the content of a document.

Parameters:

• documentId (required): UUID of the document
• content (required): New content to write

Example:

Replace the content of Scene 2 with the revised version

append_to_document

Add content to the end of a document without replacing existing content.

Parameters:

• documentId (required): UUID of the document
• content (required): Content to append
• separator (optional): Separator between existing and new content (default: two newlines)

Example:

Append this new paragraph to Chapter 5
Add these notes to the end of the scene

create_document

Create a new document or folder.

Parameters:

• title (required): Title of the new document
• parentId (optional): UUID of parent folder (defaults to Draft/Manuscript)
• documentType (optional): "Text" or "Folder" (default: "Text")
• content (optional): Initial content

Example:

Create a new chapter called "The Escape"
Create a folder called "Act Two" and add three scenes to it

delete_document

Move a document to the trash.

Parameters:

• documentId (required): UUID of the document to delete

Example:

Delete the scene called "Old Draft"

move_document

Move a document to a different folder.

Parameters:

• documentId (required): UUID of the document to move
• targetFolderId (required): UUID of the target folder
• position (optional): Position in target folder

Example:

Move "The Discovery" scene to Chapter 4

rename_document

Rename a document.

Parameters:

• documentId (required): UUID of the document
• newTitle (required): New title

Example:

Rename "Untitled Scene" to "The Confrontation"

batch_read

Read multiple documents at once. More efficient than multiple read_document calls.

Parameters:

• documentIds (required): Array of document UUIDs to read

Example:

Read all the scenes in Chapter 2

read_synopsis / write_synopsis

Read or write the synopsis (index card text) for a document.

Parameters:

• documentId (required): UUID of the document
• synopsis (required for write): Synopsis text

Example:

Show me the synopsis for Chapter 3
Update the synopsis for "The Chase" to summarize the new version

read_notes / write_notes

Read or write inspector notes for a document.

Parameters:

• documentId (required): UUID of the document
• notes (required for write): Notes content

Example:

Show me my notes for Scene 5
Add a note to Chapter 2 about the timeline

search_content

Search for content across all documents.

Parameters:

• query (required): Search query

Example:

Search for mentions of "the artifact"
Find all scenes that reference the castle

search_with_context

Search with surrounding paragraphs for better context.

Parameters:

• query (required): Search term
• contextParagraphs (optional): Paragraphs before/after to include (default: 2)

Example:

Search for "the ritual" with 3 paragraphs of context

get_compile_order

Preview what documents will be compiled and in what order.

Parameters:

• stopAtTitle (optional): Stop at document with this title (partial match)

Example:

Show me the compile order
What would be compiled up to Chapter 5?

compile_manuscript

Compile the manuscript to a PDF file.

Parameters:

• outputPath (required): Full path for the output PDF
• title (optional): Book title for cover page and PDF metadata (default: project filename)
• author (optional): Author name for cover page and PDF metadata
• stopAtTitle (optional): Stop at document with this title
• includeTitle (optional): Include document titles as headers (default: true)
• fontSize (optional): Font size in points (default: 12)
• lineSpacing (optional): Line spacing multiplier (default: 1.5)

Example:

Compile my full manuscript to D:/Writing/MyNovel.pdf
Compile with title "Keystone: Aftermath" by Dave Cilluffo
Compile everything up to Chapter 7 to D:/Writing/Draft.pdf
Compile with 14pt font and double spacing

set_include_in_compile

Toggle whether a document should be included when compiling.

Parameters:

• documentId (required): UUID of the document
• include (required): true to include, false to exclude

Example:

Exclude the "Notes" document from compile
Include "Deleted Scene" back in the compile

word_count

Get word count for a specific document or the entire manuscript.

Parameters:

• documentId (optional): UUID of document (omit for entire manuscript)

Example:

How many words are in my manuscript?
What's the word count for Chapter 3?

find_all_mentions

Find all sentences mentioning a term. Great for character/setting consistency checks.

Parameters:

• term (required): Term to search for (e.g., character name)

Example:

Find all mentions of "Sarah"
Show me every sentence that mentions "the lighthouse"

compare_descriptions

Find descriptive sentences for a term (sentences with "was", "had", "looked", etc.). Helps identify inconsistent descriptions.

Parameters:

• term (required): Term to find descriptions for

Example:

Find all descriptions of Sarah
Check how I've described the mansion throughout the book
Are my descriptions of Marcus consistent?

Important Notes

• Close Scrivener first before using this server to avoid conflicts
• The server modifies the .scrivx binder file and RTF content files directly
• Always keep backups of important projects
• Only documents marked "Include in Compile" are included in PDF export
• This is an unofficial tool and is not affiliated with Literature & Latte

How It Works

Scrivener projects (.scriv folders) contain:

• A .scrivx XML file that defines the binder structure
• Individual RTF files for each document's content
• Synopsis and notes stored as plain text and RTF files

This server parses and modifies these files directly, allowing AI assistants to interact with your project programmatically.

Support This Project

If you find this useful, consider supporting development:

License

MIT License - see for details.

Changelog

v1.3.2

• Added title/author to compile - compile_manuscript now accepts title and author parameters for cover page and PDF metadata

v1.3.1

• Fixed PDF compile formatting - Paragraphs now have proper spacing instead of running together
• Added text formatting to PDF - Bold, italic, and bold-italic are now rendered in compiled PDFs
• Improved chapter titles - Larger font (18pt), bold, with better spacing

v1.3.0

• Added utility tools: word_count, append_to_document, set_include_in_compile, read_notes, write_notes, batch_read
• Added continuity tools: search_with_context, find_all_mentions, compare_descriptions
• 22 tools total

v1.2.0

• Added compile features: get_compile_order, compile_manuscript (PDF export via pdfkit)
• Compile supports partial export with stopAtTitle parameter
• Added synopsis tools: read_synopsis, write_synopsis

v1.1.3

• Fixed empty paragraph handling - Empty lines no longer cause extra spacing in compiled output

v1.1.2

• Fixed RTF paragraph formatting - Resolved issue where \par\par patterns caused section breaks in Scrivener compile

v1.0.1

• Fixed DraftFolder detection - create_document now finds the manuscript root by type (DraftFolder) instead of requiring title to be "Draft" or "Manuscript"
• Fixed empty search query - search_content with empty query now returns empty array
• Fixed empty rename validation - rename_document rejects empty titles

v1.0.0

• Initial release with 11 core tools
• Custom RTF parser with formatting preservation
• Support for bold, italic, em-dash, en-dash

Credits

Developed by Dave Cilluffo / TwelveTake Studios

Scrivener is a registered trademark of Literature & Latte Ltd.