MCP server for Scrivener: read, write, analyze, and search your manuscripts with AI assistants.
The MCP server for Scrivener enables reading, writing, analyzing, and searching manuscripts with AI assistants. It connects Scrivener projects to AI tools to support semantic search, content analysis, and manuscript management within a Model Context Protocol workflow.
🛠️ Key Features
Read, write, analyze, and search Scrivener manuscripts via MCP
AI-assisted content analysis and semantic search
Integration centered on model-context-protocol workflows
Topics include writing tools, novel creation, and manuscript management
🚀 Use Cases
Semantic search across Scrivener projects
AI-assisted editing and writing guidance
Context-aware collaboration between writers and AI copilots
Analyzing manuscript structure, themes, and pacing
⚡ Developer Benefits
Clear MCP-based API surface for Scrivener projects
Rich metadata and tooling topics to optimize integration
Reusable components for model-context-driven workflows
Open-source-friendly structure and README excerpts
⚠️ Limitations
Data exposure limited to Scrivener project scope
Requires compatible AI assistants and MCP client tooling
Performance depends on AI model capabilities and project size
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. Listed on the official MCP Registry as io.github.writerslogic/scrivener-mcp.
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)
bash
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:
bash
npx scrivener-setup
This detects Claude Code (along with Claude Desktop and Cursor) and writes the config for you. To register it manually instead:
bash
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
bash
npx -y @smithery/cli install scrivener-mcp --client claude
Run the interactive setup to auto-detect and configure your client:
bash
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_KEY environment variable
~/.env, ~/.scrivener-mcp/.env, ~/.openai/key
macOS Keychain (service name openai-api-key)
To store your key in the macOS Keychain:
bash
security add-generic-password -s openai-api-key -a openai -w sk-your-key-here
Or export it manually:
bash
export OPENAI_API_KEY="sk-..."
This enables: content enhancement, semantic search, multi-agent analysis, character consistency checking, and intelligent compilation.
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: ...
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.
Project -- open, browse, manage
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
Documents -- read, write, create, organize
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)
Search -- find content, passages, and mentions
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
Analysis -- quality, consistency, structure
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
Compile & Export -- assemble and ship the manuscript
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
Memory -- persistent project knowledge
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.
Relationships -- entity connections and story graph
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.
Background Jobs -- long-running analysis
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
Discovery -- explore capabilities
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)
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
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
bash
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
53 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
Contributing
We welcome contributions of all sizes. Check the issue tracker for good first issue labels, or see the contributing guide for development setup.
