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
-
Clone and build:
git clone https://github.com/TwelveTake-Studios/scrivener-mcp.git cd scrivener-mcp npm install npm run build -
Add to your Claude Desktop configuration:
{ "mcpServers": { "scrivener": { "command": "node", "args": ["/full/path/to/scrivener-mcp/dist/index.js"] } } } -
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
| Tool | Description |
|---|---|
open_project | Open a Scrivener project (.scriv folder) |
get_structure | Get the hierarchical structure of the project binder |
Document Operations
| Tool | Description |
|---|---|
read_document | Read content from a document (optionally includes synopsis) |
write_document | Write/replace content in a document |
append_to_document | Append content to end of document without replacing |
create_document | Create new documents or folders |
delete_document | Move documents to trash |
move_document | Reorganize items in the binder |
rename_document | Rename documents |
batch_read | Read multiple documents at once (more efficient) |
Synopsis & Notes
| Tool | Description |
|---|---|
read_synopsis | Read the synopsis (index card text) |
write_synopsis | Write/update the synopsis |
read_notes | Read inspector notes for a document |
write_notes | Write/update inspector notes |
Search
| Tool | Description |
|---|---|
search_content | Search across all documents |
search_with_context | Search with surrounding paragraphs for context |
Compile & Export
| Tool | Description |
|---|---|
get_compile_order | Preview what will be compiled |
compile_manuscript | Export manuscript to PDF |
set_include_in_compile | Toggle document's "Include in Compile" setting |
word_count | Get word count for document or entire manuscript |
Continuity Checking
| Tool | Description |
|---|---|
find_all_mentions | Find all sentences mentioning a term |
compare_descriptions | Find descriptive sentences to check consistency |
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 onlymaxDepth(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 documentincludeSynopsis(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 documentcontent(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 documentcontent(required): Content to appendseparator(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 documentparentId(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 movetargetFolderId(required): UUID of the target folderposition(optional): Position in target folder
Example:
Move "The Discovery" scene to Chapter 4
rename_document
Rename a document.
Parameters:
documentId(required): UUID of the documentnewTitle(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 documentsynopsis(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 documentnotes(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 termcontextParagraphs(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 PDFtitle(optional): Book title for cover page and PDF metadata (default: project filename)author(optional): Author name for cover page and PDF metadatastopAtTitle(optional): Stop at document with this titleincludeTitle(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 documentinclude(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
.scrivxbinder 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
.scrivxXML 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 LICENSE for details.
Changelog
v1.3.2
- Added title/author to compile -
compile_manuscriptnow acceptstitleandauthorparameters 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
stopAtTitleparameter - 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\parpatterns caused section breaks in Scrivener compile
v1.0.1
- Fixed DraftFolder detection -
create_documentnow finds the manuscript root by type (DraftFolder) instead of requiring title to be "Draft" or "Manuscript" - Fixed empty search query -
search_contentwith empty query now returns empty array - Fixed empty rename validation -
rename_documentrejects 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.