# Scrivener MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI assistants read, write, and organize [Scrivener](https://www.literatureandlatte.com/scrivener/overview) 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)
```bash
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`
```json
{
"mcpServers": {
"scrivener": {
"command": "scrivener-mcp"
}
}
}
```
### Option 2: From Source
1. Clone and build:
```bash
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:
```json
{
"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
| 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 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:
[](https://buymeacoffee.com/twelvetake)
[](https://ko-fi.com/twelvetake)
## License
MIT License - see [LICENSE](LICENSE) 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](https://twelvetake.com)
Scrivener is a registered trademark of [Literature & Latte Ltd](https://www.literatureandlatte.com/).
