Scrivener MCP Server
Connect Scrivener 3 writing projects to Claude, ChatGPT, and other AI assistants. 60+ tools for manuscript management, writing analysis, semantic search, character/plot memory, and content enhancement.
Documentation
Scrivener MCP
Connect your Scrivener projects to Claude, ChatGPT, and other AI assistants
Install · What You Can Do · All Tools · Guides · Contributing
Scrivener MCP lets your AI assistant open, read, edit, analyze, and search your Scrivener projects directly. No copy-pasting. No exporting. Just open your novel 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. All of them auto-configure Claude Desktop on install.
npm (recommended)
npm install -g scrivener-mcp
Restart Claude Desktop. Done.
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
Setup for other MCP clients
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.
Optional: AI-powered features
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_KEYenvironment 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.
What You Can Do
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.
All Tools
60+ tools organized by workflow. Click to expand.
Project -- open, browse, save
| Tool | What it does |
|---|---|
open_project | Open a .scriv project (accepts .scriv folders or .scrivx files) |
get_structure | Browse the binder hierarchy |
get_document_info | Document metadata, parent path, location |
get_all_documents | Flat list of every document |
save_project | Save pending changes |
is_project_modified | Check for unsaved work |
Documents -- read, write, create, organize
| Tool | What it does |
|---|---|
read_document | Read document content |
write_document | Write or replace content |
create_document | Create a new document or folder |
delete_document | Move to trash |
move_document | Reorganize in the binder |
rename_document | Change title |
get_word_count | Word and character counts |
get_document_annotations | Read Scrivener annotations and footnotes |
Metadata & Search -- synopses, labels, status, search
| Tool | What it does |
|---|---|
update_metadata | Update synopsis, notes, label, status, custom metadata |
batch_update_synopsis_notes | Update multiple documents at once |
search_content | Full-text search across all documents |
semantic_search | Find passages by meaning, not just keywords |
find_analogies | Analogical reasoning (A is to B as C is to ?) |
list_trash / search_trash | Browse and search trashed documents |
recover_document | Restore from trash |
Analysis -- readability, pacing, style, feedback
| Tool | What it does |
|---|---|
analyze_document | AI-powered writing analysis |
deep_analyze_content | Comprehensive metrics (readability, pacing, emotion, style) |
critique_document | Constructive feedback on specific focus areas |
check_character_consistency | Find contradictions across the manuscript |
analyze_story_structure | Plot arc and structure analysis (requires Neo4j) |
Enhancement -- improve your prose
| Tool | What it does |
|---|---|
enhance_content | Apply a specific improvement to a document |
compile_documents | Combine documents with formatting |
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
Memory -- characters, plot, style
| Tool | What it does |
|---|---|
save_character_profile | Store character details that persist across sessions |
get_character_profiles | Retrieve all saved characters |
save_plot_thread | Track plot lines and their status |
get_plot_threads | View all plot threads |
update_style_guide | Set tone, voice, POV, tense preferences |
get_style_guide | View current style guide |
get_writing_stats | Word counts, session history, progress |
export_project_memory / import_memory | Backup and restore project memory |
Memory is stored within each .scriv project and travels with it.
Relationships -- entity connections and story graph
| Tool | What it does |
|---|---|
add_relationship | Store a relationship between characters, documents, themes, or plot threads |
find_relationships | Query entities related to a given character/theme/location |
store_chapter_order | Store the reading sequence of chapters/scenes |
character_network | Visualize character relationship network |
discover_connections | Find co-occurring entities across the manuscript |
sync_to_neo4j | Sync relationships to Neo4j (when available) |
Works without Neo4j. Relationships are stored in the Holographic Memory System and available immediately. Neo4j adds advanced graph analysis (PageRank, shortest path, communities) when connected.
Database -- advanced queries and analytics
| Tool | What it does |
|---|---|
query_database | Run custom SELECT queries on project data |
get_writing_statistics | Writing stats over a time period |
find_character_relationships | Character relationship graph (Neo4j) |
create_relationship | Define relationships between entities |
backup_databases | Backup project databases |
SQLite is included and automatic. Neo4j is optional for graph-based story analysis.
Guides
- Getting Started -- Installation, configuration, your first session
- 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
- 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:
| Feature | scrivener-mcp | jiayun | zaphodsdad | others |
|---|---|---|---|---|
| Document read/write | 60+ tools | 29 tools | read-only | basic |
| 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 | vector search + analogies + dream mode | no | no | no |
| Character/plot memory | persistent profiles, plot threads, style guide | no | no | no |
| Multi-agent analysis | roundtable critique with specialized agents | no | no | no |
| Windows support | full path handling + .scrivx discovery | partial | no | no |
| Published to npm | yes (npm i -g scrivener-mcp) | no | no | no |
| Active development | weekly | monthly | stale | stale |
| Community | 27+ stars, 9 forks, 30+ issues | 6 stars | 4 stars | minimal |
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.