Scrivener MCP

Record a typed, directed relationship between two story entities (e.g. a character "mentors" another, or a character "appears in" a document) in the project story graph. Returns the stored edge with its generated id. Use this to build the knowledge graph that find_relationships, character_network, and discover_connections then query. Requires an open project with the relationship engine initialized.

Analyze the writing quality of a single document and return a summary of readability, pacing, and the top issues found. This is the general-purpose prose analyzer: narrow it with analysisTypes to focus on style, structure, themes, characters, sentiment, or pacing. Use check_consistency for project-wide continuity instead, or enhance_content to get rewritten prose rather than a critique. Calls an external AI model. Requires an open project and a valid document id.

Analyze the prose style of one or more text samples — sentence variety, tone, voice, pacing, and other stylistic features — and return a structured style profile. Use this to characterize how something is written; use analyze_document for document-level metrics or check_plot_consistency for narrative coherence.

Cancel a queued or running background job by its type and id. Returns whether the cancellation succeeded. Cancelling an already-finished or unknown job is harmless. Use get_job_status first to check whether a job is still in progress.

THE default tool for "map my characters" / "how do my characters connect": returns the full character relationship network — every character and the typed relationships between them — for rendering a graph or analyzing cast structure. Prefer this for any whole-cast question. Use find_relationships only for one entity's connections, get_entity_references for which documents mention an entity, and suggest_connections to surface missing links. Requires an open project with the relationship engine initialized. Takes no parameters.

Scan the whole project for continuity problems and return the issues found: character contradictions, timeline conflicts, location mismatches, and dropped or inconsistent plot threads. This is the project-wide continuity checker; use analyze_document to critique a single document's prose instead. Narrow the scan with checkTypes. Requires an open project.

Scan a set of documents for plot-level inconsistencies — timeline conflicts, contradicted facts, dropped threads — and return the issues found with the documents involved. Use this for story/plot coherence across chapters; use check_consistency for general consistency checks or analyze_writing_style for prose-level analysis.

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.

Record feedback on an AI operation (e.g. "enhance_content") so it feeds the insights returned by get_writing_preferences. Provide a 1-5 rating, whether the output was kept (accepted), and/or a comment. Use after the writer reacts to AI output. Requires an open project.

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.

Compile the project's documents into a single continuous manuscript in the requested format and return the compiled text (large results are spooled to a file reference). In "standard" mode it joins documents in binder order; in "intelligent" mode it uses AI to optimize the output for a specific target such as an agent query or synopsis. To write a manuscript to disk in a publishing format (EPUB, etc.) use export_project instead. Requires an open project.

Create a new text document or folder in the binder and return its new id. Optionally set the initial body content and the parent folder; if no parent is given the item is added at the top level. Each call creates a distinct item (not idempotent). Use write_document to change content afterward. Requires an open project.

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.

Move a document to the project trash. This is reversible: the document can be listed with list_trash and brought back with restore_document until the trash is emptied in Scrivener. Deleting an already-trashed document is a no-op. Requires an open project and a valid document id.

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.

Surface previously unrecorded relationships across the project by analyzing entity co-occurrence, returning candidate connections the story graph does not yet contain. Use this to find latent links to confirm with add_relationship; use find_relationships for known connections of a specific entity. Requires an open project with the relationship engine initialized.

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.

Produce an AI-improved version of a document's text for a chosen goal (fix grammar, refine style, improve clarity, expand, summarize, or rework creatively) and return the suggested rewrite. This does NOT modify the document; review the result and call write_document to save it. Use analyze_document for a critique instead of a rewrite, or generate_content to create new text from a prompt. Calls an external AI model. Requires an open project.

Export the whole project to a publishing/interchange format. Markdown, HTML, and JSON are returned inline; DOCX (agent/editor submission), EPUB (e-readers), and PDF (print/review) are written to a file on disk and the path is returned. Use this to produce a deliverable file; use compile_documents when you want the compiled text back in the response rather than written to disk. Requires an open project.

Find every occurrence of a specific name or term (a character, place, or keyword) across all documents, returning each hit with surrounding context and its document. Use this for exact "where does X appear" lookups; use search for relevance-ranked results or semantic_search for meaning-based matches. Returns up to 50 mentions. Requires an open project.

List registered characters and locations that no document actually mentions — entities added to the registry but with no textual presence, which are candidates for removal or for prose that still needs writing. Uses exact whole-word matching, no AI. Requires an open project.

Query the story graph for entities related to a given entity, returning the connected entities and the relationship types that link them. This covers cross-references and discovered connections for a specific entity; use character_network for the whole-cast graph, or discover_connections to surface co-occurring entities project-wide. Requires an open project with the relationship engine initialized.

Generate new prose from a natural-language prompt and return the generated text, optionally steered by project context (a document, characters, or a target style) and a desired length. This creates fresh text and does not modify any document. Use enhance_content to improve existing text instead, or analyze_document to critique it. Calls an external AI model and requires an AI provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY); without one a placeholder is returned.

Generate a publishing/marketing artifact from the manuscript — a synopsis, query letter, pitch packet, elevator pitch, or book blurb — using the project content as context, and return the generated text. Use this for submission and pitching materials; use compile_documents to assemble the manuscript itself. Requires an open project with text content. Each call regenerates fresh output (not idempotent).

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).

Return metadata for a single document without its body text: title, type, word count, synopsis, label, status, parent, and custom metadata. Use this to inspect a document or to read its word count cheaply; call read_document when you need the actual prose, or get_structure for the whole binder. Requires an open project and a valid document id.

Trace the reference graph between documents and registered characters/locations, in either direction. Pass documentId to list the entities a document mentions (its cast and settings, with counts and offsets); pass entity (registry id or name) to list every document that mentions it, ranked by count. Provide exactly one of documentId or entity. Exact whole-word, case-insensitive matching against the registries — no AI. Returns empty when there are no matches or the registries are empty. Requires an open project.

Look up the status and progress of a background job previously started by queue_document_analysis, queue_project_analysis, or another async tool. Returns the job state (queued, running, completed, failed), progress, and result when finished. Poll this after enqueuing work; use cancel_job to stop a job.

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.

Return project-wide statistics: total word and document counts, plus title and author. Use this for a quick project overview; use get_structure for the per-document breakdown or get_document_info for a single document. Requires an open project.

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).

List writing goals with computed progress: percent complete, words remaining, and whether each goal is on pace given its target date and the current project word count. Use when the writer asks how close they are to a goal or for a progress dashboard; not when defining a new goal (use set_writing_goal) or forecasting a finish date from writing velocity (use predict_completion). Related: set_writing_goal. Requires an open project and the project database.

Return the current author writing preferences plus feedback insights: how much feedback has been recorded, average satisfaction per operation, and non-binding suggestions for adjusting preferences. Use to review what is currently steering AI output, or to see whether recorded feedback points to a change. Related: set_writing_preferences, collect_feedback. Requires an open project.

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.

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).

List all documents currently in the project trash, with their ids and titles. Use this to see what can be brought back with restore_document, or to confirm a delete_document call. Requires an open project. Takes no parameters.

Move a document or folder to a different parent folder in the binder, optionally at a specific position among the target folder's children. Changes only the location, not the content. Requires an open project, a valid document id, and a valid target folder id.

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.

Enqueue a background NLP analysis of one document (readability, entities, sentiment) and return a job id immediately without blocking. Poll the job with get_job_status and stop it with cancel_job. Use this for large documents where a synchronous analyze_document call would be slow; use analyze_document directly for quick, inline results.

Enqueue a background batch analysis across many documents at once and return a job id immediately. Poll progress with get_job_status and stop it with cancel_job. Use this to analyze a whole manuscript or large set of documents; for a single document prefer queue_document_analysis or the synchronous analyze_document.

Return the inline comments and footnotes attached to a document, grouped by type. Use this to review editorial notes and references without reading the full body; use read_document for the prose itself. Requires an open project and a valid document id.

Read the text of a single document. By default returns plain text; set format to "formatted" to get rich text with styling and structure preserved. Use offset and limit to page through long documents by word range instead of returning the whole thing. Use get_document_info when you only need metadata, or search/semantic_search to find content across many documents. Requires an open project and a valid document id.

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).

Read back the project's persistent memory: stored characters, world-building, plot threads, and style guide. Returns the requested store, or the full memory when memoryType is omitted or "all". Use remember to write new facts. Requires an open 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.

Store or update a fact in the project's persistent memory so later tools and sessions stay consistent: a character profile, world-building detail, plot thread, or style-guide entry. Pass an id inside data to update an existing entry, or omit it to add a new one. Use recall to read memory back. Requires an open project.

Restore a trashed document back into the binder, optionally into a specific target folder (otherwise it returns to a default location). Use list_trash to find the document id first. This is the inverse of delete_document. Requires an open project and a valid document id.

Search the open project and return matching documents with relevance-ranked snippets. By default performs an intelligent full-text/semantic search of document content; set field to "title" for a fast case-insensitive title lookup, or scope to "trash" to search only trashed documents. For meaning-based "find passages about X" queries use semantic_search; to find every occurrence of a specific name or term use find_mentions. Requires an open project.

Find passages by meaning rather than exact words, using embeddings over the project, and return the most relevant documents with similarity scores and related entities. Use this for conceptual "find passages about X" queries; use search for keyword/full-text matching and find_mentions to locate every occurrence of a specific name or term. Calls an external embedding model. Requires an open project with semantic indexing available.

Create or replace the active word-count goal for a cadence (daily, weekly, or whole project), optionally with a target date. Setting a goal of a type that already has an active goal updates that goal in place rather than stacking duplicates. Use when the writer commits to a target ("write 1000 words a day", "finish an 80k novel by December"); not when you only want to read current progress (use get_writing_goals) or log a finished session. Related: get_writing_goals, predict_completion. Requires the project database.

Set the author writing preferences that shape AI writing output (enhance_content and other generative tools). Preferences are injected into the AI prompt, so changes take effect on the next enhancement. All fields are optional and merge into the existing profile. Use when the writer states a preferred tone, complexity, length, point of view, style guide, or a custom instruction. Requires an open project (preferences persist in the project database).

Suggest characters or locations a document might be missing: entities it does not mention but that frequently co-occur — in other documents — with the entities it does mention. Deterministic co-occurrence inference (no AI), ranked by how many of the document’s entities each suggestion travels with. Use this to spot a scene that omits a character who usually appears with its cast. Returns empty when the document has no known entities. Requires an open project.

Generate AI writing suggestions for a prompt or a specific document — ideas for revision, next steps, or alternatives. Returns suggestion text. Optionally grounds the suggestions in a document's content. Use this for generative "how could this be better" help; use analyze_document for structured metrics or check_consistency to find contradictions.

Update a document's title and/or its metadata (synopsis, notes, label, status, and custom fields) in a single call. Pass only the fields you want to change; omitted fields are left untouched. To change the body text use write_document; to move it use move_document. Requires an open project and a valid document id.

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).

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.

Replace a document's text with new content, preserving the surrounding Scrivener formatting the edit did not touch (stylesheet, styles, images, footnotes) byte-for-byte. The result reports whether formatting was fully preserved; when an edit would drop non-round-trippable content it takes a Scrivener snapshot first (restorable in Scrivener) and says so. To change only the title or metadata use update_document; to add a new document use create_document. Requires an open project and a valid document id.