Scrivener
About
The definitive MCP server for Scrivener. Connect your novels, screenplays, and manuscripts to Claude, ChatGPT, and other AI assistants. 60+ tools for document management, writing analysis, content enhancement, semantic search, and character/plot tracking.
Details
- Author
- writerslogic
- GitHub stars
- 32
- Downloads
- 667
- Categories
- Productivity, Other, Knowledge Base, Search, AI
Jump to
- OPENAI_API_KEY environment variable
- ~/.env, ~/.scrivener-mcp/.env, ~/.openai/key
- macOS Keychain (service name openai-api-key)
- Getting Started -- Installation, configuration, your first session
- MCP Client Setup -- Copy-paste config for Claude Desktop, Claude Code, Cursor, and VS Code
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ScrivenerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The README includes setup instructions such as npx scrivener-setup.
list_skills
List the available skills (tool groups) — project, documents, search, analysis, compilation, memory, relationships — with a description, the tool count, whether the skill is already active, and its tool names. Use this to discover capabilities, then call use_skill to activate a group whose tools you need. Takes no parameters.
use_skill
Activate a skill so its tools become available to call. Returns the activated skill's tool names and their schemas; clients that support tools/list_changed will also see the new tools appear automatically. Call list_skills first to see the available skill names. Tools are progressively disclosed, so activate the skill you need before using its tools (most tools are pre-activated by default).
open_project
Open a Scrivener project and make it the active project for this session. Every document, structure, search, and analysis tool operates on the project opened here, so call this first. Accepts the path to a .scriv folder or the .scrivx file inside it and resolves the project automatically. Returns the project title, author, and metadata. Opening a project closes any project already open. If you do not know the path, call discover_projects first.
get_structure
Return the binder hierarchy of the open project: its folders and documents in tree order, each with id, title, type, depth, and word count. Use this to understand the manuscript layout and to obtain the document ids that read_document, write_document, and the analysis tools require. By default returns a compact flat array of [id, title, type, depth, wordCount, hasChildren] tuples to save tokens; set summaryOnly for just project-level counts. Requires an open project (call open_project first).
refresh_project
Reload the open project from disk, discarding the in-memory cache. Use this when the project has been changed by the Scrivener app or another process while open here, so that subsequent reads reflect the latest saved state. Requires an open project. Takes no parameters.
close_project
Close the currently open project, flush any pending memory/auto-save state, and clear the active session. After this, document and analysis tools have no project to act on until open_project is called again. Use this to switch projects cleanly or release file handles at the end of a session. Requires an open project. Takes no parameters.
discover_projects
Scan common locations (Documents, Desktop, and iCloud Mobile Documents) for Scrivener projects and return the paths of every .scriv folder found, searching up to three levels deep. Use this when the user refers to their project by name rather than path ("open my novel"): present the results and pass the chosen path to open_project. Does not open anything itself. Returns a list of project paths, or a message if none are found.
detect_open_project
Detect which Scrivener project the user currently has open in the desktop Scrivener app, so you can act on it without asking for a path. Use this when the user says "my project", "the project I have open", or gives a command with no project specified. Reads the open window names from the running app and resolves them to .scriv paths on disk; it does not open anything. If exactly one project is open, pass its path to open_project. macOS only right now (returns supported=false elsewhere; fall back to discover_projects). The first use may prompt macOS to allow the client app to control Scrivener.
get_compile_settings
Return the project's compile-format definitions (from Settings/compile.xml) and its taxonomy: the named compile formats and their section-layout counts, the current output file type, label and status definitions (with colors), saved collections, and user-defined section types. Use this to discover what compile formats and metadata categories a project defines before compiling or organizing. Read-only; does not run a compile. If a project has never been compiled, hasCompileSettings is false and only the taxonomy is returned. Requires an open project (call open_project first).
get_manuscript_briefing
One "where am I?" snapshot of the whole manuscript: total word count against the project draft target (with percent-to-goal and deadline), document/folder counts, the per-status and per-label breakdown, and the longest and shortest documents. Use this right after open_project to orient before diving in, instead of stitching get_statistics, get_writing_goals, and get_compile_settings together. Read-only. Requires an open project.
list_snapshots
List the snapshots Scrivener has saved of a project's documents (from the .scriv package's Snapshots/ directory). Pass documentId to list one document's snapshots, or omit it to list snapshots for every document that has any. Each entry gives the owning document id and title, a snapshotId (pass it to read_snapshot to get the text), the snapshot's title, and its date. Read-only. Returns an empty list when nothing has been snapshotted. Requires an open project (call open_project first).
read_snapshot
Return the text of a single document snapshot. Pass the documentId and the snapshotId from list_snapshots. The snapshot's RTF is converted to plain text. Read-only; does not alter the document or restore the snapshot. Requires an open project (call open_project first).
compare_snapshot
Compare a document snapshot against the current document text, or against another snapshot (pass againstSnapshotId). Returns the paragraphs added and removed and the net word-count change — use this to see what changed since a snapshot was taken. Read-only. Requires an open project (call open_project first). Get snapshot ids from list_snapshots.
create_snapshot
Take a Scrivener-native snapshot of a document's current content, restorable from Scrivener's own Snapshots browser. Use this before rewriting a document to give the writer a native rollback point. Copies the live content into the project's Snapshots directory with a title and timestamp; does not modify the document. Requires an open project and a document that has content.
verify_project_integrity
Scan the open project for structural problems and return a read-only report: binder entries with missing, malformed, or duplicate UUIDs, entries missing their type, and text documents whose backing content is unreadable or empty. Use when a project looks corrupted, after manual edits to the .scrivx file, or before a bulk operation; not when you just want the document tree (use get_structure) or a single document (use get_document_info). This tool only detects problems and never repairs them. related: get_structure, get_document_info. Requires an open project.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"scrivener": {
"scrivener": {
"command": "npx",
"args": [
"scrivener-mcp"
]
}
}
}
}McpServers
{
"scrivener": {
"command": "npx",
"args": [
"scrivener-mcp"
]
}
}<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/writerslogic/scrivener-mcp/main/assets/logo-white.svg"/>
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/writerslogic/scrivener-mcp/main/assets/logo-black.svg"/>
</picture>
</p>
<h1 align="center">Scrivener MCP</h1>
<p align="center">
<strong>Connect your Scrivener projects to Claude, ChatGPT, and other AI assistants</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/scrivener-mcp">
</a>
<a href="https://github.com/writerslogic/scrivener-mcp/actions">
</a>
<a href="https://github.com/writerslogic/scrivener-mcp/blob/main/LICENSE">
</a>
<a href="https://github.com/writerslogic/scrivener-mcp/issues">
</a>
<a href="https://github.com/writerslogic/scrivener-mcp/stargazers">
</a>
<a href="https://mseep.ai/app/writerslogic-scrivener-mcp">
</a>
<a href="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp">
</a>
</p>
<p align="center">
<a href="#install">Install</a> ·
<a href="#what-you-can-do">What You Can Do</a> ·
<a href="#all-tools">All Tools</a> ·
<a href="#guides">Guides</a> ·
<a href="#contributing">Contributing</a>
</p>
---
Scrivener MCP lets your AI assistant open, read, edit, analyze, and search your Scrivener projects directly. No copy-pasting. No exporting. Tell your assistant which project to open, and start working.
> You: Open my novel and analyze the pacing in Chapter 12.
>
> Claude: Opens your .scriv project, reads Chapter 12, runs pacing analysis.
> The first half moves well with short, tense paragraphs. The middle section slows
> considerably -- the three-page internal monologue starting at paragraph 14 stalls
> the momentum you built in the confrontation scene. Consider cutting it to a single
> paragraph and moving the backstory to Chapter 8 where Elena is first introduced.
Works with Claude Desktop, Claude Code, VS Code (Copilot/Continue), Cursor, and any MCP-compatible client. Scrivener 3 on macOS, Windows, and Linux.
Install
Pick the method that works for you. Most auto-configure Claude Desktop on install. Claude Code and other clients need one extra step -- see Claude Code below.
npm (recommended)
npm install -g scrivener-mcp
Restart Claude Desktop. Done.
Claude Code
Installing the npm package does not register the server with Claude Code -- the install-time auto-config only writes Claude Desktop's config. After installing, register the server:
npx scrivener-setup
This detects Claude Code (along with Claude Desktop and Cursor) and writes the config for you. To register it manually instead:
claude mcp add -s user scrivener -- npx scrivener-mcp
Then restart Claude Code (or run /mcp to reconnect) and Scrivener MCP appears in the server list. Drop -s user to scope it to the current project instead of all projects.
Smithery
npx -y @smithery/cli install scrivener-mcp --client claude
npx (no install)
Use directly without installing globally:
npx scrivener-mcp
Or add to your Claude Desktop config manually:
{
"mcpServers": {
"scrivener": {
"command": "npx",
"args": ["scrivener-mcp"]
}
}
}
GitHub
Install directly from the repo (latest main):
npm install -g writerslogic/scrivener-mcp
Or a specific release:
npm install -g writerslogic/scrivener-mcp#v0.5.1
Homebrew (macOS)
brew install writerslogic/tap/scrivener-mcp
Docker
docker build -t scrivener-mcp https://github.com/writerslogic/scrivener-mcp.git
docker run -i --rm -v /path/to/your/projects:/projects scrivener-mcp
<details>
<summary><strong>Setup for other MCP clients</strong></summary>
Run the interactive setup to auto-detect and configure your client:
npx scrivener-setup
This detects Claude Desktop, Claude Code, and Cursor, and writes the config for you.
For other MCP clients, point them at npx scrivener-mcp as a stdio server.
</details>
<details>
<summary><strong>Optional: AI-powered features</strong></summary>
Core features (document management, analysis, search) work without any API key. For AI-powered enhancements, the server automatically discovers your OpenAI key from common locations:
- OPENAI_API_KEY environment variable
- ~/.env, ~/.scrivener-mcp/.env, ~/.openai/key
- macOS Keychain (service name openai-api-key)
To store your key in the macOS Keychain:
security add-generic-password -s openai-api-key -a openai -w sk-your-key-here
Or export it manually:
export OPENAI_API_KEY="sk-..."
This enables: content enhancement, semantic search, multi-agent analysis, character consistency checking, and intelligent compilation.
</details>
What You Can Do
> First, open a project. The server acts on whatever .scriv project you point it at -- it has no link to the Scrivener app and can't see what you have open there. Start a conversation with "Open my Scrivener project at ~/Documents/My Novel.scriv" (or "Discover my Scrivener projects" if you don't know the path), then give your commands. On macOS you can also just say "Use the project I have open in Scrivener" -- it detects the open project and opens it (the first time, macOS asks you to allow controlling Scrivener). Do this once at the start of each conversation; the examples below all assume a project is open. If the same project is also open and unsaved in the Scrivener app, save or close it there first to avoid conflicting writes.
Manage Your Manuscript
Open any Scrivener project and work with it naturally. Read chapters, create new scenes, reorganize the binder, update synopses -- all through conversation.
> You: Create a new scene called "The Reveal" after Chapter 5, and move the old epilogue to the trash.
Analyze Your Writing
Get detailed feedback on readability, pacing, style, dialogue quality, and emotional arc. Not generic advice -- analysis grounded in your actual prose.
> You: Analyze Chapter 3. Is the pacing too slow?
>
> Claude: Readability is good (Flesch-Kincaid grade 8.2), but pacing flags:
> - 4 consecutive paragraphs of internal monologue (lines 45-78) with no action or dialogue
> - The scene is 3,200 words with only 2 scene breaks -- your other chapters average 4
> - Filter word density is 2x your manuscript average ("felt", "seemed", "noticed")
> Specific suggestions: ...
Enhance Your Prose
Apply targeted improvements: eliminate filter words, strengthen verbs, vary sentence structure, add sensory details, convert telling to showing, tighten dialogue, adjust pacing.
> You: Eliminate the filter words in Chapter 7 and strengthen the verbs.
Track Characters and Plot
Store character profiles, plot threads, and style guides that persist with your project. The AI remembers your characters across sessions.
> You: Save a character profile for Marcus: retired detective, cynical but fair, walks with a limp from an old injury, speaks in clipped sentences.
>
> Later...
>
> You: Check if Marcus is consistent across all chapters.
>
> Claude: Found an inconsistency: Marcus walks "briskly" in Chapter 9 (line 34), but his limp is referenced in Chapters 2, 5, and 11. Also, his dialogue in Chapter 4 uses long flowing sentences, which contradicts the "clipped sentences" note in his profile.
Search by Meaning
Find passages by what they're about, not just keyword matching. "Find scenes where the protagonist feels isolated" works even if the word "isolated" never appears. Powered by the Holographic Memory System -- works offline, no API key needed.
> You: Find all scenes where Elena and Marcus are alone together.
Track Relationships
Store and query relationships between characters, locations, themes, and plot threads. No Neo4j required -- relationships live in the semantic memory engine and persist with your project.
> You: Who is connected to Marcus? What plot threads involve the lighthouse?
Compile and Export
Combine chapters into a single manuscript with configurable formatting, separators, and structure preservation. Export the result inline as Markdown, HTML, or JSON, or write a DOCX, EPUB, or PDF file to disk for submission, e-readers, or print.
All Tools
53 tools organized by workflow. To keep token usage low, tools load progressively -- project tools at startup, document and search tools when you open a project, and the rest on demand (your AI client activates them automatically). Set SCRIVENER_MCP_EAGER_TOOLS=1 to load everything at once.
<details>
<summary><strong>Project</strong> -- open, browse, manage</summary>
| Tool | What it does |
|------|-------------|
| open_project | Open a .scriv project (accepts .scriv folders or .scrivx files) and make it active |
| discover_projects | Scan common locations for Scrivener projects when you don't know the path |
| detect_open_project | Detect the project currently open in the Scrivener app (macOS) so you don't need a path |
| get_structure | Browse the binder hierarchy (folders, documents, word counts) |
| refresh_project | Reload from disk after external edits |
| close_project | Close the active project and flush pending changes |
| verify_project_integrity | Read-only scan for structural problems (missing/duplicate UUIDs, unreadable content) |
| get_compile_settings | Read the project's compile formats and taxonomy -- labels/statuses (with colors), collections, section types |
</details>
<details>
<summary><strong>Documents</strong> -- read, write, create, organize</summary>
| Tool | What it does |
|------|-------------|
| get_document_info | Metadata for one document (title, type, word count, synopsis, label, status) |
| read_document | Read content; format: "formatted" for rich text, offset/limit to page long docs |
| write_document | Replace a document's content (atomic, with pre-write backup) |
| create_document | Create a new text document or folder |
| update_document | Change title and/or metadata (synopsis, notes, label, status, custom fields) |
| move_document | Reorganize within the binder |
| delete_document | Move to trash (reversible) |
</details>
<details>
<summary><strong>Search</strong> -- find content, passages, and mentions</summary>
| Tool | What it does |
|------|-------------|
| search | Keyword/full-text search; field: "title" for titles, scope: "trash" for trash |
| semantic_search | Find passages by meaning using embeddings, with similarity scores |
| find_mentions | Locate every occurrence of a specific name or term, with context |
| list_trash | List trashed documents |
| restore_document | Restore a document from trash |
| read_annotations | Read a document's comments and footnotes |
</details>
<details>
<summary><strong>Analysis</strong> -- quality, consistency, structure</summary>
| Tool | What it does |
|------|-------------|
| analyze_document | AI writing analysis; focus with aspects (structure, style, pacing, themes...) |
| check_consistency | Project-wide continuity check; scope for plot, characters, or timeline |
| analyze_writing_style | Style-focused analysis |
| check_plot_consistency | Plot-thread consistency check |
| suggest_improvements | AI-generated improvement suggestions |
| enhance_content | Suggest a specific improvement to a document |
| generate_content | Generate new prose from a prompt and context |
| set_writing_goal | Set a word-count goal (daily, weekly, or whole project) with an optional target date |
| get_writing_goals | List goals with progress -- percent complete, words remaining, on-pace status |
| set_writing_preferences | Set author preferences (tone, complexity, length, POV, style guide) that steer AI output |
| get_writing_preferences | Show current preferences plus feedback insights and suggestions |
| collect_feedback | Record a rating/comment on an AI operation to inform those insights |
Enhancement types: eliminate-filter-words, strengthen-verbs, vary-sentences, add-sensory-details, show-dont-tell, improve-flow, enhance-descriptions, strengthen-dialogue, fix-pacing, expand, condense, rewrite
</details>
<details>
<summary><strong>Compile & Export</strong> -- assemble and ship the manuscript</summary>
| Tool | What it does |
|------|-------------|
| compile_documents | Combine documents with formatting; mode: "intelligent" for AI-optimized output |
| export_project | Write the manuscript to disk -- Markdown, HTML, JSON inline, or DOCX, EPUB, PDF as a file |
| get_statistics | Project-level word/document/character counts |
| generate_marketing_materials | Draft synopsis, query letter, pitch, and related materials |
</details>
<details>
<summary><strong>Memory</strong> -- persistent project knowledge</summary>
| Tool | What it does |
|------|-------------|
| remember | Store information that persists across sessions with the project |
| recall | Retrieve previously stored memory |
Memory is stored within each .scriv project and travels with it.
</details>
<details>
<summary><strong>Relationships</strong> -- entity connections and story graph</summary>
| Tool | What it does |
|------|-------------|
| add_relationship | Store a relationship between characters, locations, themes, or plot threads |
| find_relationships | Query entities related to a given character/theme/location |
| discover_connections | Find co-occurring entities across the manuscript |
| character_network | The character relationship network |
| get_document_references | List the registered characters/locations a document mentions, with counts and positions |
| get_referencing_documents | Find every document that mentions a given character or location, ranked by count |
| find_orphaned_entities | List registered characters/locations that no document actually mentions |
| suggest_connections | Suggest entities a document may be missing, inferred from cross-document co-occurrence |
Works without Neo4j -- relationships live in the Holographic Memory System and are available immediately. The document cross-reference tools are fully deterministic (exact whole-word matching, no AI) and need no external services; Neo4j adds advanced graph analysis when connected.
</details>
<details>
<summary><strong>Background Jobs</strong> -- long-running analysis</summary>
| Tool | What it does |
|------|-------------|
| queue_document_analysis | Enqueue an async analysis of one document; returns a job id |
| queue_project_analysis | Enqueue an async analysis of the whole project |
| get_job_status | Poll progress/results for a queued job |
| cancel_job | Cancel a queued or running job |
</details>
<details>
<summary><strong>Discovery</strong> -- explore capabilities</summary>
| Tool | What it does |
|------|-------------|
| list_skills | List the available tool groups and their tools |
| use_skill | Activate a tool group (most are pre-activated by default) |
</details>
Guides
- Getting Started -- Installation, configuration, your first session
- MCP Client Setup -- Copy-paste config for Claude Desktop, Claude Code, Cursor, and VS Code
- Writing with AI -- Analysis workflows, enhancement strategies, memory management
- Troubleshooting -- Common issues and fixes
- Token Optimization -- How the server minimizes context window usage
- Architecture -- How the server works, module structure, data flow
- Scrivener Compatibility -- Supported Scrivener versions, platforms, and format coverage
- Scrivener File Format -- The reverse-engineered .scriv format, what we read vs. infer, and safe-modification guidance
- Contributing -- Development setup, code conventions, adding new tools
Requirements
- Node.js 18+
- Scrivener 3 project files (.scriv)
- macOS, Windows, or Linux
- Optional: OpenAI API key for AI-powered features
- Optional: Neo4j for character relationship graphs
Development
git clone https://github.com/writerslogic/scrivener-mcp.git
cd scrivener-mcp
npm install
npm run dev # Development mode with hot reload
npm run build # Compile TypeScript
npm test # Run tests
npm run typecheck # Type checking only
Why This One?
Several Scrivener MCP servers exist. Here's how they compare:
<!-- comparison-start -->
| Feature | scrivener-mcp | jiayun | zaphodsdad | others |
|---------|:-:|:-:|:-:|:-:|
| Document read/write | 60+ tools | 29 tools | read-only | basic |
| RTF / rich text support | yes | no | no | no |
| Writing analysis | readability, pacing, style, emotion | basic metrics | no | no |
| Content enhancement | 12 types (filter words, verbs, show-don't-tell…) | no | no | no |
| Semantic search (offline) | vector + analogies + dream mode | no | no | no |
| Character consistency check | yes | no | no | no |
| Character / plot memory | persistent profiles, plot threads, style guide | no | no | no |
| Relationship graphs | HMS triplets + optional Neo4j | no | no | no |
| Multi-agent analysis | roundtable critique with specialised agents | no | no | no |
| Story structure analysis | yes (requires Neo4j) | no | no | no |
| Token optimisation | progressive skill loading, compact JSON | no | no | no |
| Batch document operations | yes | partial | no | no |
| Export / compilation | yes — multiple formats | basic | no | no |
| Windows support | full path handling + .scrivx discovery | partial | no | no |
| Install method | npm · Homebrew · Docker · Smithery | manual clone | manual clone | varies |
| Published to npm | yes (npm i -g scrivener-mcp) | no | no | no |
| License | AGPL-3.0 / commercial dual-license | MIT | — | varies |
| Active development | weekly | stale | occasional | stale |
| Community | ⭐ 32 · 14 forks · 10 issues | ⭐ ? | ⭐ 5 | minimal |
<!-- comparison-end -->
Contributing
We welcome contributions of all sizes. Check the issue tracker for good first issue labels, or see the contributing guide for development setup.
Areas where help is especially welcome:
- Test coverage (#18)
- Windows testing and path handling
- Scrivener 2 compatibility testing
- Documentation improvements (#25)
License
AGPL-3.0 © WritersLogic, Inc.
Free for personal use and open-source projects. Commercial license available for proprietary integration. See COMMERCIAL_LICENSE.md for details.
<p align="center">
<a href="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp">
</a>
</p>
<p align="center">
<a href="https://github.com/writerslogic/scrivener-mcp">GitHub</a> ·
<a href="https://www.npmjs.com/package/scrivener-mcp">npm</a> ·
<a href="https://github.com/writerslogic/scrivener-mcp/issues">Issues</a> ·
<a href="./CHANGELOG.md">Changelog</a>
</p>
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
