Scrivener MCP Server

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.

🚀 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

🧠 NEW Holographic Hyperdimensional Memory (HHM)

• 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

• GPU Acceleration: WebGPU-powered operations with CPU fallback

• Multi-modal Learning: Text, documents, relationships, and temporal sequences

• Creative Combinations: Dream mode generates novel concept associations

• Memory Evolution: Background learning and concept refinement

• Consistency Checking: Detect contradictory information across documents

• SIMD Optimization: Vectorized operations for maximum performance

• Vector Caching: LRU cache system for frequently accessed patterns

🛠️ 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

MIT © David Condrey

🤝 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

📚 Documentation

• Holographic Memory Guide - Complete guide to the new HHM system

🔗 Links

• GitHub Repository

• NPM Package

• Issue Tracker

• Changelog