Scrivener MCP Server

What is Scrivener MCP Server about?

Scrivener MCP Server provides a Model Context Protocol interface that lets Claude (and other AI agents) interact with Scrivener 3 projects. It exposes operations for opening projects, reading and writing documents, managing the binder hierarchy, handling RTF formatting, and storing rich semantic memory—all without external services such as Redis.

How to use Scrivener MCP Server?

Install the package globally:
```
npm install -g scrivener-mcp
```
Run the server (the simplest way is with npx):
```
npx scrivener-mcp
```

Configure Claude Desktop (automatic on first run). If needed, add the following to claude_desktop_config.json:

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

Call the defined tools via JSON‑RPC from Claude or any MCP‑compatible client. Example (JavaScript):

open_project('/path/to/Novel.scriv');
const txt = read_document('UUID-OF-DOCUMENT');
const analysis = deep_analyze_content('UUID-OF-DOCUMENT');
enhance_content('UUID-OF-DOCUMENT', 'strengthen-verbs');

Key Features

Core Scrivener Operations: open projects, CRUD for documents and folders, metadata updates, trash management.
Full RTF Support: parse, preserve, and generate Scrivener‑specific RTF, including annotations and Unicode.
AI‑Powered Content Analysis: readability scores, style assessment, cliché detection, emotional arc tracking, and actionable suggestions.
Smart Content Enhancement: 12+ AI‑driven improvement types (filter‑word removal, verb strengthening, sensory detail addition, pacing control, etc.).
Holographic Memory System (Rust native): 10k‑dimensional semantic vectors, semantic search, analogical reasoning, GPU‑accelerated batch APIs, concept generation, and dream mode.
Persistent Project Memory: character profiles, plot threads, style guide, writing statistics, auto‑save with version history.
Compilation & Export: combine multiple documents, preserve or strip formatting, custom separators.
Database Layer: built‑in SQLite for structured data and optional Neo4j graph for relationship analysis.
Zero‑Config / No Redis: embedded queue system runs out‑of‑the‑box.

Use Cases

Author Draft Editing: request Claude to rewrite a chapter, strengthen verbs, or add sensory details directly inside Scrivener.
Manuscript Review: run deep_analyze_content on each document to receive readability metrics, pacing heatmaps, and cliché reports.
Semantic Search: locate scenes by meaning (e.g., “first meeting between protagonist and love interest”) using semantic_search.
Character & Plot Management: store and retrieve character arcs, relationships, and plot threads via the memory API.
Batch Enhancements: apply enhance_content across a list of document IDs before a final export.
Research Integration: extract research notes from web HTML and attach them to relevant sections with extract_research_data.
Graph‑Based Story Analysis: use Neo4j tools to visualize character networks or narrative flow.

FAQ

Q: Do I need Redis or any external queue? A: No. The server includes an embedded queue system, so installation is all that is required.

Q: Which Node version is required? A: Node 18+ (the package declares engines with Node 18 or later).

Q: Can I run the server without an API key? A: Yes. Core features work offline; AI‑powered analysis and enhancement require an external LLM provider key, which can be supplied via environment variables if desired.

Q: How is the Holographic Memory accessed? A: Through the hhm/* tool namespace (e.g., semantic_search, hhm/memorize/text, hhm/dream). All calls are JSON‑RPC calls handled by the same MCP server.

Q: What if automatic Claude Desktop configuration fails? A: Run the setup script manually:

npx scrivener-mcp setup

or add the configuration snippet shown above to claude_desktop_config.json.

Q: Is the server compatible with Windows/macOS/Linux? A: Yes. It is a pure Node.js package with optional Rust native bindings that compile on all major OSes.

Q: How do I back up my project memory? A: Use export_project_memory to dump the full memory JSON, and import_memory to restore it later.

Q: Can I query the underlying SQLite database directly? A: Yes, via the query_database tool or by opening the .scrivener-databases/scrivener.db file with any SQLite client.

A powerful Model Context Protocol (MCP) server that enables Claude AI to seamlessly interact with Scrivener projects. This server provides comprehensive document management, AI-powered content analysis, and advanced writing assistance capabilities - all without requiring external services like Redis.

v0.4.0 - Major reliability and performance update. See CHANGELOG.md for details.

🚀 Quick Start

Installation

npm install -g scrivener-mcp

✨ Features:

Automatic Claude Desktop configuration - Just restart Claude Desktop after installation
No Redis or external services required - Built-in embedded queue system
Zero configuration - Works out of the box
AI providers optional - Core features work without API keys

Manual Configuration (Optional)

If automatic setup didn't work, you can manually configure:

# Run the setup script
npx scrivener-mcp setup

# Or manually add to claude_desktop_config.json:

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

Uninstalling

# Remove the package and configuration
npm uninstall -g scrivener-mcp

✨ Features

📚 Core Scrivener Operations

Project Management: Open and manage Scrivener .scriv projects
Document CRUD: Read, write, create, delete, and move documents and folders
Metadata Management: Update document titles, keywords, and custom metadata
Project Structure: Navigate and manipulate the hierarchical binder structure

📝 Advanced RTF Support

Full RTF Parsing: Complete support for Scrivener's RTF document format
Formatted Content: Preserve and manipulate bold, italic, underline, and other formatting
Scrivener Annotations: Extract and preserve Scrivener-specific annotations and comments
Unicode Support: Handle international characters and special symbols

🤖 AI-Powered Content Analysis

Deep Writing Analysis: Comprehensive metrics including Flesch scores, readability, pacing
Style Assessment: Sentence variety, vocabulary complexity, adverb usage analysis
Quality Indicators: Detection of clichés, filter words, repetitiveness
Emotional Analysis: Track emotional arcs and tension levels
Smart Suggestions: Actionable recommendations for improvement
Legacy Analysis: Basic readability metrics and passive voice detection

🧠 Intelligent Memory Management

Project Memory: Persistent storage within each Scrivener project
Character Profiles: Track character details, relationships, and arcs
Plot Threads: Manage multiple storylines and their progression
Style Guide: Maintain consistent tone, voice, POV, and tense
Writing Statistics: Track progress, word counts, and productivity
Auto-save: Automatic backups with version history

✍️ Smart Content Enhancement

Smart Editing: 12+ enhancement types for improving prose
Filter Word Elimination: Remove unnecessary qualifiers
Verb Strengthening: Replace weak verbs with powerful alternatives
Sentence Variation: Improve rhythm and flow
Sensory Enhancement: Add vivid sensory details
Show Don't Tell: Convert telling to showing
Pacing Control: Adjust story tempo
Content Expansion/Condensing: Meet word count targets

📖 Document Compilation & Export

Multi-document Compilation: Combine multiple documents into single output
Format Preservation: Option to maintain or strip RTF formatting
Custom Separators: Configure how documents are joined

🧠 Holographic Memory System (HMS) - Rust Native

Rust-native engine: High-performance napi-rs bindings with rayon parallel encoding
Semantic Search: Find documents by meaning, not just keywords
Analogical Reasoning: Discover relationships like "protagonist:hero :: antagonist:?"
Auto-Memorization: Documents automatically stored in 10,000-dimensional semantic space
Zero-copy ingestion: Buffer and memmap2 paths avoid UTF-8 copies at the napi boundary
Batch APIs: Single native call per operation; no serial loops across the boundary
Multi-modal Learning: Text, documents, relationships, and temporal sequences
Creative Combinations: Dream mode generates novel concept associations
End-to-end tracing: trace_id flows from JSON-RPC request through Rust spans
Type-safe: TypeScript types and JSON schemas auto-generated from Rust structs via ts-rs/schemars

🛠️ Available Tools

The MCP server provides 75+ powerful tools for comprehensive Scrivener integration:

📁 Project Operations

open_project(path) - Open a Scrivener project
get_structure(options?) - Get the project's hierarchical structure
- Options: maxDepth (limit tree depth), folderId (get specific folder), includeTrash (include trash), summaryOnly (return counts only)
get_document_info(documentId) - Get document metadata with full parent hierarchy and location
get_project_metadata() - Get project-level metadata

📄 Document Operations

read_document(documentId) - Read plain text content
read_document_formatted(documentId) - Read with RTF formatting preserved
write_document(documentId, content) - Write content to document
get_document_annotations(documentId) - Get Scrivener annotations

🗂️ File Management

create_document(parentId?, title, type?) - Create new document or folder
delete_document(documentId) - Delete document or folder
move_document(documentId, newParentId?) - Move document to new location

🔍 Metadata & Search

update_metadata(documentId, metadata) - Update document metadata
search_content(query, options?) - Search across all documents (excludes trash)
get_word_count(documentId?) - Get word/character counts

🗑️ Trash Management

list_trash() - List all documents in the trash folder
search_trash(query, options?) - Search only within trashed documents
recover_document(documentId, targetParentId?) - Recover document from trash

📊 Analysis & Compilation

analyze_document(documentId) - Deep AI-powered content analysis
deep_analyze_content(documentId) - Comprehensive writing metrics and suggestions
critique_document(documentId, focusAreas?) - Get constructive feedback
compile_documents(documentIds, separator?, preserveFormatting?) - Compile multiple documents

✨ Content Enhancement

enhance_content(documentId, enhancementType, options?) - Apply AI improvements
- 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 Management

save_character_profile(name, role, description?, traits?, arc?) - Store character data
get_character_profiles() - Retrieve all character profiles
update_style_guide(tone?, voice?, pov?, tense?) - Set writing preferences
get_style_guide() - Get current style guide
save_plot_thread(name, description, status?, documents?) - Track plot lines
get_plot_threads() - View all plot threads
get_writing_stats() - Get project statistics
export_project_memory() - Export complete memory data

🔧 Additional Tools

get_all_documents(includeTrash?) - Get flat list of all documents
save_project() - Save any pending changes to the project
is_project_modified() - Check if project has unsaved changes
read_document_rtf(documentId) - Read document with RTF formatting preserved
update_document_context(documentId, summary?, themes?, pacing?) - Update document memory context
add_custom_context(key, value) - Add custom context to project memory
get_custom_context(key?) - Get custom context from project memory
update_writing_session(wordsWritten, duration?) - Update writing session statistics
extract_research_data(html, keywords?) - Extract research data from web content
import_memory(memoryData) - Import project memory from exported data
update_document_synopsis_notes(documentId, synopsis?, notes?) - Update synopsis and/or notes for a document
batch_update_synopsis_notes(updates) - Update synopsis and/or notes for multiple documents at once

🧠 NEW Holographic Memory (HHM) Tools

semantic_search(query, k?, threshold?) - Find documents by semantic meaning
find_analogies(a, b, c) - Discover analogical relationships (A:B :: C:?)
hhm/memorize/text(text, id?) - Store text in semantic memory
hhm/memorize/document(document) - Store document with structure
hhm/memorize/relationship(subject, relation, object) - Store semantic relationships
hhm/query/text(text, k?) - Query memory with text
hhm/query/analogy(a, b, c) - Find analogical completions
hhm/concepts/generate() - Generate novel concept combinations
hhm/dream(duration?) - Enter creative recombination mode
hhm/consistency/check(memoryIds) - Verify memory consistency
hhm/stats() - Get HHM system statistics
hhm/benchmark/run(dimensions?) - Run performance benchmarks
hhm/benchmark/gpu() - Test GPU acceleration capabilities
hhm/cache/clear() - Clear vector cache
hhm/cache/stats() - Get cache performance metrics

🗄️ Database Tools (Advanced)

get_database_status() - Get status of SQLite and Neo4j databases
query_database(query, params?) - Execute SELECT queries on SQLite database
get_writing_statistics(days?) - Get writing statistics for specified period
record_writing_session(wordsWritten, durationMinutes?, documentsWorkedOn?, notes?) - Record a writing session
analyze_story_structure() - Analyze document flow, character arcs, and themes using Neo4j
find_character_relationships(characterId) - Find all relationships for a character
create_relationship(fromId, fromType, toId, toType, relationshipType, properties?) - Create relationships between entities
get_content_analysis_history(documentId, analysisType?) - Get historical analysis data
backup_databases(backupPath?) - Create backup of project databases

📄 RTF Format Support

This MCP server includes comprehensive RTF (Rich Text Format) support specifically designed for Scrivener's document format:

RTF Parsing: Converts RTF to structured content with formatting preserved
RTF Generation: Creates valid RTF from plain or formatted text
Scrivener Extensions: Handles Scrivener-specific RTF extensions and annotations
Character Encoding: Properly handles Unicode and special characters
Metadata Extraction: Extracts document metadata from RTF info groups

🏗️ Architecture

Core Components

ScrivenerProject - Main class for project operations
RTFHandler - Comprehensive RTF parsing and generation
DatabaseService - Manages SQLite and Neo4j database operations
MemoryManager - Persistent project memory and context storage
ContentAnalyzer - Deep writing analysis and metrics
ContentEnhancer - AI-powered content improvement engine
HolographicMemorySystem - 10,000-dimensional semantic memory with GPU acceleration
MCP Server - Tool definitions and request handling

Data Storage

SQLite Database - Stored in .scrivener-databases/scrivener.db within each project
- Documents, characters, plot threads, themes, writing sessions
- Content analysis history and relationships
Neo4j Graph Database - Optional graph database for relationship analysis
- Document flow, character networks, theme progression
- Falls back gracefully if not available
Memory Files - Stored in .ai-memory folders for quick access
Automatic backups maintain history and data integrity
All data persists between sessions and travels with the project

💻 Usage Examples

Basic Workflow

// Open a project
open_project("/path/to/MyNovel.scriv")

// Get project structure
get_structure()

// Read a document
read_document("UUID-OF-DOCUMENT")

// Analyze content
deep_analyze_content("UUID-OF-DOCUMENT")

// Apply enhancements
enhance_content("UUID-OF-DOCUMENT", "strengthen-verbs")

Synopsis and Notes Management

// Update synopsis for a single document
update_document_synopsis_notes("UUID-OF-CHAPTER", {
  synopsis: "Elizabeth meets Mr. Darcy at the assembly ball and takes an instant dislike to him.",
  notes: "Important first impression scene - sets up central conflict"
})

// Batch update multiple documents
batch_update_synopsis_notes([
  {
    documentId: "UUID-OF-CHAPTER-1",
    synopsis: "Introduction to Elizabeth and her family",
    notes: "Character establishment chapter"
  },
  {
    documentId: "UUID-OF-CHAPTER-2", 
    synopsis: "The Netherfield ball",
    notes: "Major social event - introduces Bingley and Darcy"
  }
])

Database Operations

// Check database status
get_database_status()

// Query documents with custom SQL
query_database("SELECT title, word_count FROM documents WHERE word_count > 1000")

// Record a writing session
record_writing_session({
  wordsWritten: 1250,
  durationMinutes: 45,
  documentsWorkedOn: ["UUID-1", "UUID-2"],
  notes: "Productive morning session"
})

// Get writing statistics
get_writing_statistics(30) // Last 30 days

// Analyze story structure (requires Neo4j)
analyze_story_structure()

// Find character relationships in graph
find_character_relationships("CHARACTER-UUID")

// Create document relationship
create_relationship(
  "CHAPTER-1-UUID", "document",
  "CHAPTER-2-UUID", "document", 
  "FOLLOWS"
)

Character Management

// Save a character profile
save_character_profile({
  name: "Elizabeth Bennet",
  role: "protagonist",
  description: "Intelligent and witty young woman",
  traits: ["independent", "prejudiced", "romantic"],
  arc: "Overcomes initial prejudice to find true love"
})

// Retrieve all characters
get_character_profiles()

Style Consistency

// Set style guide
update_style_guide({
  tone: ["witty", "romantic", "formal"],
  voice: "Jane Austen-esque",
  pov: "third-limited",
  tense: "past"
})

// Apply style-aware enhancements
enhance_content("UUID", "match-style")

Writing Analysis

// Get comprehensive analysis
const analysis = deep_analyze_content("UUID")
// Returns metrics, suggestions, quality indicators, pacing analysis

// Get focused critique
critique_document("UUID", ["pacing", "dialogue"])

🛡️ Error Handling

The server includes robust error handling for:

Invalid project paths
Missing documents
RTF parsing failures
File system errors
Malformed project structures
Memory corruption recovery

👨‍💻 Development

npm run dev       # Development mode with hot reload
npm run build     # Build TypeScript
npm run lint      # ESLint
npm run typecheck # TypeScript checking

📋 Requirements

Node.js 18+
TypeScript 5.0+
Valid Scrivener 3 project files

📜 License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💖 Support

If you find this project helpful, consider:

⭐ Starring the repository
🐛 Reporting bugs or requesting features
☕ Buying me a coffee
📣 Sharing with other Scrivener users