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"/>
    <img src="https://raw.githubusercontent.com/writerslogic/scrivener-mcp/main/assets/logo-black.svg" alt="Scrivener MCP Logo" width="200"/>
  </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">
    <img src="https://img.shields.io/npm/v/scrivener-mcp.svg" alt="npm version"/>
  </a>
  <img src="https://img.shields.io/npm/dm/scrivener-mcp.svg" alt="npm downloads"/>
  <a href="https://github.com/writerslogic/scrivener-mcp/actions">
    <img src="https://github.com/writerslogic/scrivener-mcp/actions/workflows/ci.yml/badge.svg" alt="build"/>
  </a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/writerslogic/scrivener-mcp"><img src="https://api.securityscorecards.dev/projects/github.com/writerslogic/scrivener-mcp/badge" alt="OpenSSF Scorecard"></a>
  <a href="https://github.com/writerslogic/scrivener-mcp/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/writerslogic/scrivener-mcp" alt="license"/>
  </a>
  <img src="https://img.shields.io/node/v/scrivener-mcp" alt="node version"/>
  <a href="https://github.com/writerslogic/scrivener-mcp/issues">
    <img src="https://img.shields.io/github/issues/writerslogic/scrivener-mcp" alt="issues"/>
  </a>
  <a href="https://github.com/writerslogic/scrivener-mcp/stargazers">
    <img src="https://img.shields.io/github/stars/writerslogic/scrivener-mcp" alt="stars"/>
  </a>
  <a href="https://mseep.ai/app/writerslogic-scrivener-mcp">
    <img src="https://img.shields.io/badge/MseeP-verified-green.svg" alt="MseeP verified"/>
  </a>
  <a href="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp">
    <img src="https://glama.ai/mcp/servers/writerslogic/scrivener-mcp/badges/score.svg" alt="scrivener-mcp MCP server score"/>
  </a>
</p>

<p align="center">
  <a href="#install">Install</a> &middot;
  <a href="#what-you-can-do">What You Can Do</a> &middot;
  <a href="#all-tools">All Tools</a> &middot;
  <a href="#guides">Guides</a> &middot;
  <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](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/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](https://registry.modelcontextprotocol.io) 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](#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
```

### npx (no install)

Use directly without installing globally:

```bash
npx scrivener-mcp
```

Or add to your Claude Desktop config manually:

```json
{
  "mcpServers": {
    "scrivener": {
      "command": "npx",
      "args": ["scrivener-mcp"]
    }
  }
}
```

### GitHub

Install directly from the repo (latest main):

```bash
npm install -g writerslogic/scrivener-mcp
```

Or a specific release:

```bash
npm install -g writerslogic/scrivener-mcp#v0.5.1
```

### Homebrew (macOS)

```bash
brew install writerslogic/tap/scrivener-mcp
```

### Docker

```bash
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:

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

</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:

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

</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](https://www.npmjs.com/package/holographic-memory) -- 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

56 tools organized by workflow. To keep to