Scrivener MCP
by writerslogic
README.md
### Scrivener MCP
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/logo-white.svg"><img align="left" width="96" src="assets/logo-black.svg" alt="Scrivener MCP logo"></picture>
MCP server for Scrivener: connect your novels, screenplays, and manuscripts to Claude, ChatGPT, and
any AI assistant, with document management, writing analysis, content enhancement, offline semantic
search, and character/plot tracking.
<br clear="left">
Start with the [safe first session](docs/getting-started.md#first-successful-editorial-session),
then use [editorial review and workflows](docs/editorial-workflows.md),
[export presets](docs/export-presets.md), [Content Credentials](docs/content-credentials.md), or the
[Windows guide](docs/install-windows.md). [Compatibility evidence](docs/SCRIVENER_COMPATIBILITY.md)
records actual coverage and limits.
[](https://github.com/writerslogic/scrivener-mcp/actions/workflows/ci.yml)
[](https://github.com/writerslogic/scrivener-mcp/actions/workflows/codeql.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/writerslogic/scrivener-mcp)
[](https://www.npmjs.com/package/scrivener-mcp)
[](https://github.com/writerslogic/scrivener-mcp/blob/main/LICENSE)
<p align="center">
<a href="#install">Install</a> ·
<a href="#mac-app-draftbridge-for-scrivener-499">Mac App</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 exporting, no copy-pasting text back and forth. Tell it which project to open and start
working.
> **You:** Open my novel and analyze the pacing in Chapter 12.
>
> **Claude:** _Opens the .scriv project, reads Chapter 12, runs pacing analysis._ The first half
> moves well, but the middle stalls — a three-page internal monologue starting at paragraph 14 kills
> the momentum you built in the confrontation scene. Consider cutting it to a paragraph and moving
> the backstory to Chapter 8.
Works with [Claude Desktop](https://claude.ai/download),
[Claude Code](https://docs.anthropic.com/en/docs/claude-code), VS Code (Copilot/Continue), Cursor,
and any MCP-compatible client. Reads Scrivener 3 projects on the
[supported platforms](#requirements). Listed on the
[official MCP Registry](https://registry.modelcontextprotocol.io) as
`io.github.writerslogic/scrivener-mcp`.
## Install
### Mac app: Draftbridge for Scrivener, $4.99
**Not a terminal person?**
**[Draftbridge for Scrivener](https://buy.stripe.com/14A8wHbm64Y0dR8fFdc7u01)** is the ready-made
Mac app. It finds your AI apps — Claude Desktop, BoltAI, Cursor, VS Code, LM Studio, Raycast, Claude
Code — connects Scrivener MCP to each with one click, shows your projects, and repairs the
connection after an app update. No Terminal, no Node.js, no settings files. One-time $4.99, up to 3
Macs, signed and notarized by Apple.
<p align="center">
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/draftbridge/ready-dark.png"><img src="assets/draftbridge/ready-light.png" alt="Draftbridge showing Claude Desktop and BoltAI connected, and the Scrivener projects it found" width="380"></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/draftbridge/purchase-dark.png"><img src="assets/draftbridge/purchase-light.png" alt="The Draftbridge purchase window" width="300"></picture>
</p>
The server, setup tool, and Claude Desktop extension here stay free and open source. The app is
closed source; the fee buys the notarized build and supports development. See the
[Mac install guide](./docs/install-mac.md) and [FAQ](./docs/faq.md). Report app problems with the
`mac-app` label.
### Free: Claude Desktop extension or command line
Prefer to do it yourself? The `.mcpb` extension (Claude Desktop only) and the terminal setup below
do the same job for free.
From a terminal:
```bash
npm install -g scrivener-mcp
```
Restart Claude Desktop and it's ready. Other clients need one more step:
```bash
npx scrivener-setup
```
This finds Claude Desktop, Claude Code, Cursor, VS Code, LM Studio, BoltAI, and Raycast and
configures them for you, then confirms the server starts. No Node.js on your Mac? See the
[Mac install guide](./docs/install-mac.md). To set up Claude Code by hand instead:
`claude mcp add -s user scrivener -- npx scrivener-mcp`, then restart it (or run `/mcp`).
<details>
<summary><strong>Other ways to install</strong></summary>
**npx, no install**
```bash
npx scrivener-mcp
```
or add it to Claude Desktop's config directly:
```json
{
"mcpServers": {
"scrivener": { "command": "npx", "args": ["scrivener-mcp"] }
}
}
```
**From GitHub**
```bash
npm install -g writerslogic/scrivener-mcp # latest main; requires pinned Rust/wasm-pack
npm install -g writerslogic/scrivener-mcp#v0.12.0 # a specific release
```
**Homebrew (macOS)**
```bash
brew install writerslogic/tap/scrivener-mcp
```
**Docker**
```bash
docker build --platform linux/amd64 -t scrivener-mcp https://github.com/writerslogic/scrivener-mcp.git
docker run --platform linux/amd64 -i --rm -v /path/to/your/projects:/projects scrivener-mcp
```
The container uses Linux x64 with glibc because the pinned Narrative Lens 0.2.0 package has no Linux
ARM64 or musl binary. Linux ARM64 and musl hosts can use this Docker configuration; ARM hosts need
Docker's amd64 emulation. The image runs as the non-root `node` user;
mounted project directories must permit that user to read and write.
Any other MCP client: point it at `npx scrivener-mcp` as a stdio server.
</details>
<details>
<summary><strong>Optional: AI-powered features</strong></summary>
Document management, deterministic analysis, local passage search, and project memory work with no
API key. Provider-assisted interpretation, generation and enhancement use Anthropic, OpenAI or
OpenRouter. Set more than one and Claude handles chat by default; override with `AI_PROVIDER=openai`
or `AI_PROVIDER=openrouter` (OpenRouter defaults to `anthropic/claude-sonnet-4.6`, change it with
`OPENROUTER_MODEL`). If the active provider fails on an account-level error — bad key, no credit, an
outage — the server retries on the next one you've configured. If your MCP client supports
[sampling](https://modelcontextprotocol.io/docs/concepts/sampling), chat-based features can run
through the client's own model on legacy MCP connections, no separate key needed. MCP 2026-07-28 connections currently use configured providers for AI features; modern multi-round sampling is not implemented. Passage retrieval runs locally
through Holographic Memory 0.6.4; interpretation and explanations are optional provider features.
Keys are picked up automatically from:
- `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY`
- `~/.env` or `~/.scrivener-mcp/.env`
- `~/.anthropic/key`, `~/.openai/key`, `~/.openrouter/key`
- macOS Keychain (`anthropic-api-key` / `openai-api-key` / `openrouter-api-key`)
```bash
security add-generic-password -s anthropic-api-key -a anthropic -w sk-ant-your-key-here # Keychain
export ANTHROPIC_API_KEY="sk-ant-..." # or export it directly
```
</details>
<details>
<summary><strong>Optional: offline embedding and reranking models</strong></summary>
Local passage search works without installing a model runtime. To use your own offline ONNX
embedding or reranking models with a global installation, install the optional runtime alongside the
server:
```bash
npm install -g scrivener-mcp '@huggingface/transformers@^4.3.2'
```
For a local installation, run the same command without `-g` in the server's installation directory.
Set `SCRIVENER_WARM_EMBED_MODEL_PATH` to a complete local model directory and provide
`SCRIVENER_WARM_EMBED_MODEL_ID` and `SCRIVENER_WARM_EMBED_REVISION`. Set
`SCRIVENER_WARM_RERANK_MODEL_PATH` to enable a local reranker. No model weights are downloaded; the
available options are listed in [.env.example](.env.example).
</details>
## What You Can Do
> For manuscript operations, open a project first. The server has no link to the Scrivener app
> itself and can't see what's open there. Say _"Open my Scrivener project at
> `~/Documents/My Novel.scriv`"_, or _"Discover my Scrivener projects"_ if you don't know the path.
> On macOS, _"Use the project I have open in Scrivener"_ works too (the first time, macOS will ask
> permission to control Scrivener). Do this once per conversation. If the project is also open and
> unsaved in Scrivener itself, save or close it there first, or the two can write over each other.
**Manage your manuscript.** Read chapters, create scenes, reorganize the binder, update synopses —
all through conversation. _"Create a new scene called 'The Reveal' after Chapter 5, and move the old
epilogue to the trash."_
**Analyze your writing.** Readability, pacing, style, dialogue quality, emotional arc — grounded in
your actual prose, not generic advice. Ask whether a chapter's pacing is off and get specifics:
which paragraphs stall, how the scene compares to your other chapters, filter-word density against
your own average.
**Enhance your prose.** Targeted edits: cut filter words, strengthen verbs, vary sentence structure,
add sensory detail, turn telling into showing, tighten dialogue, fix pacing.
**Track characters and plot.** Character profiles, plot threads, and style guides persist with the
project across sessions. Save a profile for a character once; a consistency check months later
catches contradictions — dialogue that doesn't sound like them, a limp that disappears for a
chapter.
**Search by meaning.** [Warm 0.6.4](https://www.npmjs.com/package/writerslogic-warm) combines native
BM25 with local embeddings and optional cross-encoder reranking. Configure local ONNX models for
general semantic search; the default encoder covers a disclosed English story-concept vocabulary.
Results include exact passages, locations and saved revisions; changed passages update incrementally.
No embedding provider is required. See [local search configuration](docs/editorial-workflows.md#find-passages-locally).
**Track relationships.** Record and query how characters, locations, themes, and plot threads
connect. Relationships persist in the project's local SQLite state. Discovery proposes unrecorded
character/location pairs using saved-text co-occurrence with source revisions.
**Compile and export.** Assemble chapters into one manuscript with your own formatting and structure
preserved. Export inline as Markdown, HTML, or JSON, or write a DOCX, EPUB, or PDF to disk.
**Sign and validate exports.** Activate `credentials` with `use_skill({"name":"credentials"})`, then
call `c2pa_capabilities` to inspect the installed SDK. Export a PDF with `export_project`, sign it
to a new embedded output with `sign_content_credentials`, and check that output with
`validate_content_credentials`. Credential operations run locally without an open project and use
administrator-configured signing material. They do not establish human authorship or formal C2PA
conformance. See [Content Credentials](docs/content-credentials.md) for setup, mode coverage and
limits.
## All Tools
84 tools organized by workflow. MCP 2026-07-28 connections list all of them at once. On earlier
protocol versions, tools load progressively to keep token usage low — project tools at startup,
document and search tools once a project is open, the rest on demand. Set
`SCRIVENER_MCP_EAGER_TOOLS=1` to load everything up front.
<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 |
| `get_manuscript_briefing` | One "where am I?" snapshot: words vs. target (% to goal), document/status/label counts, longest/shortest documents |
| `list_snapshots` | List Scrivener snapshots (title, date) for one document or the whole project |
| `read_snapshot` | Read a snapshot's text as plain text, with word count |
| `compare_snapshot` | Diff a snapshot against the current document (or another snapshot): paragraphs added/removed and net word change |
| `create_snapshot` | Take a Scrivener-native snapshot of a document (restorable from Scrivener's own Snapshots browser) before editing |
</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 saved content with revision checks, native snapshots and disclosed formatting risks |
| `review_changes` | Propose, preview, selectively approve or reject, apply batches, recover and undo saved edits |
| `manuscript_dashboard` | Interactive binder, scene context, pacing, findings and review; text fallback for other clients |
| `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` | Literal full-text search across the active binder; `field: "title"` for titles, `scope: "trash"` for trash |
| `semantic_search` | Local concept-vector passage retrieval, with scores, context and source revisions; no API key |
| `search_passages` | Local keyword, bounded English concept, or hybrid retrieval with exact quoted evidence |
| `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` | Analyze complete saved text; `analysisTypes` steers provider issues, with explicit broad local fallback and revision checks |
| `check_consistency` | Evidence-backed continuity report with source revisions, canon and inferred candidates |
| `continuity_findings` | Confirm, dismiss, resolve and recheck evidence-bound continuity findings |
| `analyze_writing_style` | Style-focused analysis |
| `check_plot_consistency` | Plot-thread consistency check |
| `suggest_improvements` | AI-generated improvement suggestions |
| `enhance_content` | Propose a complete saved-document rewrite with source revisions; maximum 12000 UTF-16 characters |
| `generate_content` | Generate prose from a prompt, saved-text excerpts and character profiles with revision-checked 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 |
| `analyze_manuscript_local` | Local manuscript findings with exact evidence, author controls, coverage, persistent baselines and revision comparisons |
| `analyze_narrative_annotations` | Check author-supplied causality, knowledge, promises, subtext and other annotations against saved quotations |
| `analyze_craft_local` | Offline readability, grammar, syntax-tension, dialogue, and word-frequency report for one document (narrative-lens, no AI call) |
| `check_continuity_local` | Offline timeline and world-state continuity pass across the manuscript |
| `analyze_foreshadowing_local` | Offline setup/payoff tracking across scenes |
| `measure_voice_drift_local` | Compare a character's earlier vs later dialogue for voice drift |
| `analyze_opening_local` | Offline opening cues, source ranges and coverage; editorial quality remains unassessed |
| `check_style_local` | Line-edit one document for adverbs, filter words, hedges, clichés, passive voice, nominalizations, and personal tics, each with line and column (bluepencil, no AI call) |
| `find_repetition_local` | Echoes (a word reappearing within a window) and repeated phrases, with both locations |
| `analyze_rhythm_local` | Sentence-length distribution, monotonous runs, overlong sentences, and repeated openers |
| `analyze_dialogue_tags_local` | Dialogue ratio and every quoted line's tag classified as plain, showy, adverb-modified, or untagged |
| `manuscript_style_report_local` | Per-document style density across the manuscript with word-weighted means and outliers |
Manuscript comparisons include `comparisonBaseline.name` and its original `envelope`, alongside the
current result's `envelope`, so both saved source revisions remain identifiable after a baseline name
is reused.
**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; `mode: "structured"` compiles the Draft folder with the binder hierarchy as headings and honors "Include in Compile" (no AI), `mode: "intelligent"` for AI-optimized output |
| `export_project` | Write the manuscript to disk -- Markdown, HTML, JSON inline, or DOCX, EPUB, PDF as a file |
| `read_result` | Retrieve large compiled/analysis results in bounded UTF-8 chunks without filesystem tools |
| `export_manuscript` | Preflight and export submission DOCX, beta-reader DOCX and validated EPUB presets |
| `get_statistics` | Project-level word/document/character counts |
| `generate_marketing_materials` | Draft synopsis, query letter, pitch, and related materials |
Intelligent compilation returns provider warnings, explicit quality availability, and saved-source
revisions. Rewrites require the complete source to fit 12000 UTF-16 characters; otherwise the
complete original is preserved. Quality opinions cover at most 4000 characters and identify that
coverage. Marketing generation reads the saved Draft by default; use `documentIds` to select a
smaller scope within the same 12000-character limit. Both reject source changes during generation
and provide `read_result` references for large output.
</details>
<details>
<summary><strong>Content Credentials</strong> -- local asset signing and validation</summary>
Activate the `credentials` skill on demand; these tools do not require an open project.
| Tool | What it does |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `c2pa_capabilities` | Inspect actual SDK availability, declared format/mode coverage, limits and unassessed conformance status |
| `sign_content_credentials` | Sign a local asset to a distinct new embedded or supported `.c2pa` sidecar output using administrator-configured credentials |
| `validate_content_credentials` | Validate a local asset and optional sidecar; report integrity separately from signer trust, with raw reports opt-in |
Format declarations are not proof of native compatibility. Use the
[Content Credentials guide](docs/content-credentials.md) and per-format native evidence before
making coverage claims.
</details>
<details>
<summary><strong>Memory</strong> -- persistent project knowledge</summary>
| Tool | What it does |
| --------------- | ---------------------------------------------------------------------------------------- |
| `remember` | Store information that persists across sessions with the project |
| `manage_series` | Create, join or leave an explicitly scoped series of selected projects |
| `story_bible` | Curate shared characters, aliases, locations, world rules and chronology with provenance |
| `recall` | Retrieve previously stored memory |
Project memory travels within each .scriv project. Explicit series memberships and shared facts use
the server's persistent registry; see
[editorial workflows](docs/editorial-workflows.md#curate-a-project-or-series-bible).
`remember` validates nested records and acknowledges the saved snapshot with its revision and record
ID. Use that ID for updates; identical creations reuse their ID, and unknown update IDs fail.
Unrecorded profile fields, style preferences and writing statistics stay absent. `worldBuilding`
stores named records, for example `{ name: "Moon Harbor", type: "location" }`; `all` merges custom
JSON by key. Requests are capped at 64 KiB and complete project memory at 16 MiB. Large `recall`
results use `read_result`. Earlier custom world data remains available under `recall` with `all`.
</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 unrecorded pairs of known characters/locations that co-occur in saved Draft documents, with source revisions |
| `character_network` | The character relationship network |
| `get_entity_references` | Trace the reference graph in either direction: entities a document mentions (by documentId), or documents mentioning an entity (by entity) |
| `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 |
Relationship tools use project-owned SQLite without an external service. Storage admits up to
10000 relationships; names contain at most 128 UTF-16 characters and labels 64. Discovery covers
the characters and locations already recorded in that graph, up to 256 entities, 1000 Draft
documents, 2 Mi UTF-16 source characters and a source-character count multiplied by entity count
of at most 134217728. Its score is the
fraction of documents mentioning both entities among those mentioning either; it is a candidate
association, not a confirmed story fact. Result limits disclose omitted candidates, and large
responses use `read_result`. Relationship queries page in stable identity order using `nextOffset`
and `graphRevision`; edits require restarting the query. Document cross-reference tools use the
character/location registries and saved text, including Research and Draft items excluded from
Compile. Document queries read only the requested document; entity-wide queries and suggestions
inspect all active text within the same source limits. They disclose missing registries, reject
source/registry changes, and preserve every admitted match offset (up to 1000000 positions and
16 MiB of serialized mention records).
</details>
<details>
<summary><strong>Background Jobs</strong> -- long-running analysis</summary>
| Tool | What it does |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `queue_document_analysis` | Analyze supplied document text asynchronously; returns a job id |
| `queue_project_analysis` | Analyze an ordered batch of supplied document texts |
| `get_job_status` | Poll progress/results for a queued job |
| `get_queue_stats` | Inspect project-scoped queue counts, connectivity and legacy migration guidance |
| `editorial_workflow` | Run chapter review, continuity audit or beta-reader preparation with durable progress and resuming |
| `cancel_job` | Request cancellation; running embedded work finishes internally and its result is discarded |
Queued analysis always runs local prose analysis and includes readability by default. Optional
named entities require a native build with ONNX support and a loaded NER model; unavailable results
are explicit. Optional sentiment uses a local lexicon heuristic. Source revisions hash the supplied
UTF-8 text, and the envelope identifies this raw policy separately from saved RTF analysis and saved
project controls. Project batches preserve input order and run sequentially unless `parallel` is
selected, with at most five documents in flight. Large completed results return a `_ref` retrieved
through `read_result`. Redis/KeyDB cannot remove an active job; embedded cancellation prevents work
that has not started and discards the result of work already running.
`suggest_improvements` accepts `async: true` for the same suggestion result through `get_job_status`.
With `useContext: true`, `documentId` is required: generation uses up to the first 16000 UTF-16
characters of that saved document and rejects a changed revision. Its result reports the exact
excerpt range, truncation and source revision. The default `useContext: false` sends only the prompt.
Suggestions use the configured provider or client sampling, and queued generation is not automatically
retried. Large synchronous and queued results use `read_result` references.
`analyze_writing_style` accepts 1–64 nonempty text samples, each up to 64000 UTF-16 characters.
Its provider prompt includes at most 8000 characters including separators; coverage reports the
range used from every sample, including any omitted samples. Missing or malformed profile fields
are explicitly unavailable, partial finding lists preserve valid entries, and sample revisions
hash the original supplied UTF-8 text. Large profiles also use `read_result` references.
</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 another tool group on demand |
</details>
## Guides
- **[Getting Started](./docs/getting-started.md)** -- Installation, configuration, your first
session
- **[MCP Client Setup](./docs/CLIENT_SETUP.md)** -- Copy-paste config for Claude Desktop, Claude
Code, Cursor, and VS Code
- **[Writing with AI](./docs/writing-with-ai.md)** -- Analysis workflows, enhancement strategies,
memory management
- **[Troubleshooting](./docs/troubleshooting.md)** -- Common issues and fixes
- **[Token Optimization](./docs/token-optimization.md)** -- Response limits and measured context
costs
- **[0.14 Validation](./docs/release-validation-0.14.md)** -- Candidate evidence, supported scope
and remaining qualification limits
- **[Architecture](./docs/architecture.md)** -- How the server works, module structure, data flow
- **[Scrivener Compatibility](./docs/SCRIVENER_COMPATIBILITY.md)** -- Supported Scrivener versions,
platforms, and format coverage
- **[Content Credentials](./docs/content-credentials.md)** -- Local C2PA signing and validation,
administrator setup, tested modes and conformance limits
- **[Scrivener File Format](./docs/scrivener-format.md)** -- The reverse-engineered `.scriv` format,
what we read vs. infer, and safe-modification guidance
- **[Fuzzing](./docs/fuzzing.md)** -- Jazzer.js target and OSS-Fuzz integration details
- **[Contributing](./CONTRIBUTING.md)** -- Development setup, code conventions, adding new
tools
## Requirements
- **Stable Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`** (24.22.1 or newer on Node 24 recommended)
- **Scrivener 3** project files (.scriv)
- Native npm/npx installs: macOS x64/ARM64, Windows x64, or Linux x64 with glibc. Architecture
refers to the Node.js runtime.
- Optional: Anthropic, OpenAI, or OpenRouter API key for provider-backed AI features
- Optional: Neo4j for persistence and advanced graph queries; core relationship tools work without
it
The patched floors protect Node TLS paths used by the pinned CAI native SDK; SQLite 13 also requires
Node-API 10. Node 23 and 25 are excluded. See the
[runtime compatibility policy](docs/forward-compatibility.md#runtime-and-dependency-changes).
## Development
See the [compatibility and upgrade policy](docs/forward-compatibility.md) for runtime checks,
protocol contracts, dependency upgrades and the stable release gate.
```bash
git clone https://github.com/writerslogic/scrivener-mcp.git
cd scrivener-mcp
npm install --ignore-scripts
# Install the pinned Rust/wasm-pack tools listed in native/c2pa-binding/README.md
npm run build:c2pa # Generate the engine from source
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?
A few Scrivener MCP servers exist. Our column describes the current server; other feature claims
come from each project's own docs, published package, and advertised tools, last re-read on
**2026-10-22**; stars, forks, activity, and published version were refreshed
<!-- comparison-refreshed -->2026-11-09<!-- /comparison-refreshed -->. "No" means undocumented — not
necessarily impossible through the connected AI client.
<!-- comparison-start -->
| Feature | **scrivener-mcp** | [jiayun](https://github.com/jiayun/scrivener-mcp) | [TwelveTake](https://www.npmjs.com/package/@twelvetake/scrivener-mcp) | [Scrivener Assistant](https://github.com/elnino1/scrivener-assistant) | [ricopicone](https://github.com/ricopicone/scrivener-mcp) | [zaphodsdad](https://github.com/zaphodsdad/scrivener-mcp) |
|---------|:-:|:-:|:-:|:-:|:-:|:-:|
| Public MCP tools | 84 | 30 | 22 | 38 | 18 | 10 |
| Manuscript access | read/write | read/write | read/write | read-only; writes sidecar data/metadata | read-only by default; opt-in content/notes/synopsis writes | read-only |
| RTF handling | formatted reads; fidelity-preserving span writes | reads/writes document content | reads/writes document content | converts RTF to text; manuscript read-only | RTF-to-text reads; snapshot-protected content writes | converts RTF to text; read-only |
| Built-in writing analysis | readability, pacing, style, emotion, AI critique | readability, style, sentiment | continuity comparison | agent-driven five-point review workflow | no dedicated analysis tool | no dedicated analysis tool |
| Content generation/enhancement | generation + 12 targeted enhancement types | no | no | brainstorm/draft agent workflow | no | no |
| Local semantic retrieval | local concept vectors, BM25 and quoted passages | no | no | no | no | no |
| Continuity/project memory | persistent memory + consistency checks | persistent notes + consistency checks | mention/description comparison | world bible, story state, characters, locations, review history | no persistent memory | no persistent memory |
| Relationship tooling | persistent relationships, networks, reference graph; optional Neo4j | no | no | human-editable relations data | no | no |
| Token optimization | progressive skill loading, compact output, paged reads | no documented equivalent | no documented equivalent | no documented equivalent | scoped binder/chapter reads | scoped overview/read tools |
| Export / compilation | Markdown, HTML, JSON, DOCX, EPUB, PDF | compile + whole-draft export | PDF | saves AI drafts; no manuscript export documented | no | no |
| Windows support | native CI verified; synthetic projects | yes (prebuilt binary) | yes | not documented | not documented | yes |
| Installation | npm, Homebrew, Docker, or the Draftbridge Mac app | crates.io, prebuilt binary, or source | npm package (deprecated) | MCPB or source | source / `uv` | source / `pip install -e` |
| License | AGPL-3.0 / commercial dual-license | MIT | MIT | MIT | not declared | MIT |
| Repository/package status | weekly activity; npm `0.12.0` | occasional activity | removed from npm | weekly activity | occasional activity; no releases | repository unavailable |
| Community | ⭐ 71 · 25 forks | ⭐ 7 | source repository unavailable | ⭐ 1 | ⭐ 0 | unavailable |
<!-- comparison-end -->
Counts and feature claims can change. Follow the linked projects for their own latest documentation.
The table is generated from [`docs/comparison.yml`](./docs/comparison.yml) — edit claims there, not
here.
### The alternative that isn't an MCP server
Scrivener can also **Sync to External Folder**, writing each document out as RTF or plain text,
which any generic file-access MCP server (like
[`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem))
can then read and write.
It's free and works today. What you lose is everything tied to the actual project — binder
hierarchy, metadata, labels and status, snapshots, compile settings, RTF formatting — and edits land
in the sync folder rather than the project itself, so a bad edit gets reconciled by Scrivener on the
next sync instead of caught before it happens. Fine for occasional read-only help with prose; not if
you want the structure to survive the round trip.
## Contributing
We welcome contributions of all sizes. Check the
[issue tracker](https://github.com/writerslogic/scrivener-mcp/issues) for `good first issue` labels,
or see the [contributing guide](./CONTRIBUTING.md) for development setup.
**Areas where help is especially welcome:**
- Test coverage ([#18](https://github.com/writerslogic/scrivener-mcp/issues/18))
- Windows testing and path handling
- Scrivener 2 compatibility testing
- Documentation improvements ([#25](https://github.com/writerslogic/scrivener-mcp/issues/25))
## Security
Found a vulnerability? Please report it privately — see [SECURITY.md](./SECURITY.md).
## License
AGPL-3.0 © [WritersLogic, Inc.](https://github.com/writerslogic)
Scrivener is a trademark of Literature & Latte Ltd. This project is independent and is not
affiliated with, endorsed by, or sponsored by Literature & Latte.
Free for personal use and open-source projects. Commercial license available for proprietary
integration. See [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md) for details.
---
Also from WritersLogic: **[WritersProof](https://writersproof.com)** witnesses your keystrokes,
pauses, and revisions as you write, then seals that process into tamper-evident, independently
verifiable proof you wrote it yourself — AI accusations, settled with evidence instead of your word.
<p align="center">
<a href="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp">
<img src="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp/badges/card.svg" alt="scrivener-mcp MCP server"/>
</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>
MCP 2026-07-28 uses `server/discover` and a stable full tool catalog. Each request supplies the protocol version and client capabilities in standard MCP `_meta`. `open_project` returns `projectHandle` in text and structured content; pass it as an ordinary argument on subsequent project tool calls. The legacy `com.writerslogic/project` request metadata token is also accepted. Handles expire on close, reopen or restart. Calls are serialized per modern stdio connection. Legacy MCP initialization, implicit project scope and progressive skill discovery remain available.
Each connection admits at most 32 active or queued tool calls and 16 MiB of retained request parameters, with a burst of 120 attempts and refill of two attempts per second. Rejections are explicit and report retry guidance. Canceled queued work releases its slot; running work retains capacity until it settles. These limits do not bound total process memory, tool results or native worker allocations. Prefer the documented report page defaults and follow revision-bound continuation cursors when retrieving large reports.
TDQS
A4/5.0
Scored across 57 tools
Disambiguation3/5
Most tools have clearly differentiated purposes, especially around document CRUD, snapshots, search modes, and export. However, the cluster of analysis and feedback tools—analyze_document, analyze_writing_style, check_consistency, check_plot_consistency, and suggest_improvements—has meaningful overlap and requires careful description-reading to select correctly.
Naming Consistency4/5
The naming convention is overwhelmingly verb_noun snake_case with consistent prefixes like get_, list_, create_, read_, write_, and set_. A few bare-verb or noun-style exceptions such as search, remember, recall, and character_network deviate slightly, preventing a perfect score.
Tool Count1/5
At 57 tools, this server is in the extreme mismatch range and presents a very heavy namespace for agents to navigate. The skills-based progressive disclosure mitigates discovery cost, but it does not reduce the total surface, and many analysis and generation tools could likely be consolidated.
Completeness5/5
The tool surface covers the full Scrivener workflow: project discovery and session lifecycle, document CRUD and trash recovery, snapshots, metadata, multiple search modes, AI analysis and generation, goals, memory, relationship graphs, compile/export, and background jobs. There are no obvious dead ends for the stated domain.
Maintenance
ActivityActive
ResponsivenessOutdated data