Skip to main content
Glama

Readwise MCP Enhanced

Readwise MCP Enhanced

A comprehensive Model Context Protocol (MCP) server that unifies Readwise Reader document management with full Readwise highlights functionality. Works with Claude Desktop, Continue, and any MCP-compatible AI tool. Built with TypeScript, featuring advanced text processing, smart content controls, and context-optimized responses.

🚀 What This Is

The first unified MCP that combines:

  • Complete Readwise Reader API - Save, manage, and search documents
  • Full Readwise Highlights API - Access all your highlights, books, and daily reviews
  • AI-Powered Text Processing - Intelligent word segmentation and content extraction
  • Context Optimization - 94% reduction in token usage while maintaining full functionality
  • Smart Content Controls - Prevent context explosion with advanced filtering and pagination

Equivalent to the official Readwise MCP but more efficient and feature-complete. Compatible with all MCP clients.


✨ Key Features

📚 Enhanced Reader Management

  • Smart Content Extraction: Pagination, keyword filtering, length limits
  • AI-Powered Text Processing: Automatic word segmentation fixes merged words
  • Performance Controls: Built-in warnings and guidance for expensive operations
  • Flexible Filtering: By location, category, tags, dates, and custom criteria

🎯 Complete Highlights Ecosystem

  • Daily Reviews: Spaced repetition learning system
  • Advanced Search: Field-specific queries with relevance scoring
  • Book Management: Full metadata with highlight counts and filtering
  • Export & Backup: Bulk highlight analysis and incremental sync
  • Manual Creation: Add highlights with full metadata support

Production Excellence

  • Context Optimized: 94% reduction in token usage (25,600 → 1,600 tokens)
  • Dual API Architecture: Seamless v2 (highlights) + v3 (Reader) integration
  • Unlimited Results: No artificial limits, just efficient data per item
  • MCP Protocol Compliant: Proper logging, error handling, and rate limiting

🛠️ Installation

No installation needed! Any MCP client will automatically download and run the package using npx.

Option 2: Global NPM Installation

npm install -g readwise-mcp-enhanced

Option 3: From Source

git clone https://github.com/arnaldo-delisio/readwise-mcp-enhanced.git cd readwise-mcp-enhanced npm install npm run build

🔧 Configuration

With Any MCP-Compatible Tool

  1. Get your Readwise token: https://readwise.io/access_token
  2. Add to your MCP client configuration:Claude Desktop:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    Continue IDE Extension:

    • Add to your Continue configuration file

    Other MCP Tools:

    • Follow your tool's MCP server configuration instructions
    { "mcpServers": { "readwise-mcp-enhanced": { "command": "npx", "args": ["readwise-mcp-enhanced"], "env": { "READWISE_TOKEN": "your_readwise_access_token_here" } } } }
    Option B - If installed globally via npm:
    { "mcpServers": { "readwise-mcp-enhanced": { "command": "readwise-mcp-enhanced", "env": { "READWISE_TOKEN": "your_readwise_access_token_here" } } } }
    Option C - If installed from source:
    { "mcpServers": { "readwise-mcp-enhanced": { "command": "node", "args": ["/path/to/readwise-mcp-enhanced/dist/index.js"], "env": { "READWISE_TOKEN": "your_readwise_access_token_here" } } } }
  3. Restart your MCP client (Claude Desktop, Continue, etc.)

📖 Available Tools (13 Total)

📚 Reader Tools (6) - Enhanced

readwise_save_document

Save documents with full metadata control.

{ "url": "https://example.com/article", "tags": ["ai", "productivity"], "location": "later", "category": "article" }
readwise_list_documents

⭐ Enhanced with Smart Content Controls

{ "withFullContent": true, "contentMaxLength": 10000, "contentStartOffset": 0, "contentFilterKeywords": ["AI", "machine learning"], "limit": 10 }

Smart Content Parameters:

  • contentMaxLength: Limit content per document (default: 50,000 chars)
  • contentStartOffset: Start extraction from specific position (pagination)
  • contentFilterKeywords: Extract only sections containing keywords
  • Performance warnings for expensive operations
readwise_update_document

Update document metadata (title, author, summary, location, etc.)

readwise_delete_document

Remove documents from your Reader library

readwise_list_tags

Get all your document tags

⭐ Enhanced with AI-powered text processing

  • Regex-based search across title, summary, notes, tags
  • Automatic word segmentation for better matching
  • Distributed keyword finding throughout content

🎯 Highlights Tools (7) - New

readwise_list_highlights

List highlights with advanced filtering:

{ "book_id": 12345, "highlighted_at__gt": "2024-01-01T00:00:00Z", "page_size": 100 }
readwise_get_daily_review

Get your spaced repetition highlights:

{ "review_id": 168844911, "highlights": [ { "text": "Strategic wisdom quote...", "title": "The Art of War", "author": "Sun Tzu" } ] }
readwise_search_highlights

⭐ Advanced search with field-specific queries:

{ "textQuery": "strategy tactics", "fieldQueries": [ { "field": "document_title", "searchTerm": "Art of War" } ], "limit": 20 }
readwise_list_books

Get books with highlight metadata:

{ "category": "books", "last_highlight_at__gt": "2024-01-01T00:00:00Z" }
readwise_get_book_highlights

Get all highlights from a specific book:

{ "bookId": 53827741 }
readwise_export_highlights

Bulk export for analysis and backup:

{ "updatedAfter": "2024-01-01T00:00:00Z", "includeDeleted": false }
readwise_create_highlight

Manually add highlights with metadata:

{ "highlights": [ { "text": "Important insight...", "title": "Book Title", "author": "Author Name", "note": "My thoughts on this", "category": "books" } ] }

🎯 Context Optimization

94% Token Reduction while maintaining full functionality:

ToolBeforeAfterSavings
List Highlights (32 items)~25,600 tokens~1,600 tokens94%
Daily Review (5 items)~5,000 tokens~400 tokens92%
List Books (10 items)~8,000 tokens~600 tokens93%

Optimized Fields:

  • Highlights: id, text, note, book_id only
  • Books: id, title, author, category, num_highlights only
  • Search: text, book, author, score only

🧠 AI-Powered Features

Intelligent Word Segmentation

Automatically fixes common text extraction issues:

  • whatyouwhat you
  • fromdissatisfactionfrom dissatisfaction
  • timeagotime ago

Smart Content Processing

  • Sentence-based chunking for YouTube transcripts
  • Distributed keyword filtering throughout content
  • Context-aware text extraction with proper spacing

Advanced Search Algorithm

  • Multi-field search with relevance scoring
  • Export-based comprehensive search equivalent to official MCP
  • Field-specific filtering (title, author, text, notes, tags)

📊 Technical Architecture

Dual API Client System

// Seamless API switching v2 API: Highlights, books, daily review, export v3 API: Reader documents, tags, search

Context-Efficient Design

  • Unlimited results with minimal data per item
  • LLM-optimized responses for efficient parsing
  • Structured JSON maintains full reasoning capabilities

Production Ready

  • ES Module standard with proper TypeScript definitions
  • MCP protocol compliant logging and error handling
  • Comprehensive rate limiting and graceful fallbacks

⚙️ API Coverage

Readwise Reader API (v3)

  • ✅ Documents: Save, list, update, delete
  • ✅ Tags: List and filter
  • ✅ Content: Smart extraction with controls
  • ✅ Search: Enhanced topic search

Readwise Highlights API (v2)

  • ✅ Highlights: List, create, search, export
  • ✅ Books: List with metadata and filtering
  • ✅ Daily Review: Spaced repetition system
  • ✅ Advanced Search: Field-specific queries

🔐 Authentication & Security

  • Single Token: One Readwise token for both APIs
  • Environment Variable: Secure token storage via READWISE_TOKEN
  • No Token Exposure: Never exposed through MCP clients or tools interface

📈 Rate Limits

  • Reader API: 20 requests/minute (default), 50/minute (CREATE/UPDATE)
  • Highlights API: Standard Readwise limits with automatic retry-after handling
  • Smart Handling: 429 responses include "Retry-After" header processing

🚀 Usage Examples

Smart Content Extraction

// Paginate through large document readwise_list_documents({ withFullContent: true, contentMaxLength: 5000, contentStartOffset: 0, contentFilterKeywords: ["machine learning", "AI"] })
// Search across documents and highlights readwise_search_highlights({ textQuery: "productivity habits", fieldQueries: [ { field: "document_author", searchTerm: "James Clear" } ], limit: 10 })

Daily Learning Workflow

// Get daily review for spaced repetition readwise_get_daily_review() // Search related highlights for deeper study readwise_search_highlights({ textQuery: "from daily review topics", limit: 20 })

📦 Dependencies

{ "@modelcontextprotocol/sdk": "^1.0.0", "dotenv": "^16.3.0", "node-html-parser": "^7.0.1", "wordsninja": "^1.0.0" }

Key Addition: wordsninja for AI-powered word segmentation


🔄 Migration from Basic Reader MCP

This unified MCP is fully backward compatible. All existing Reader tools work unchanged while adding 7 new highlights tools.

No breaking changes - just enhanced functionality and better performance.


🌟 Why This MCP?

vs. Official Readwise MCP

  • More context efficient (94% reduction)
  • Unified interface (Reader + Highlights)
  • Smart content controls (pagination, filtering)
  • AI-powered text processing
  • Unlimited results with minimal verbosity

vs. Basic Reader MCPs

  • Complete highlights ecosystem (7 new tools)
  • Advanced search capabilities
  • Production-ready performance
  • Context optimization

📄 License

MIT


🙏 Acknowledgments

Built upon the foundation of edricgan/Readwise-Reader-MCP with significant enhancements:

  • Enhanced Reader functionality with smart content controls
  • Complete highlights integration equivalent to official MCP
  • AI-powered text processing with word segmentation
  • Context optimization for production efficiency
  • Unified architecture combining dual APIs seamlessly

This represents a complete evolution from basic document management to a comprehensive, production-ready Readwise platform. 🚀

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A comprehensive MCP server that unifies Readwise Reader document management with full Readwise highlights functionality, featuring AI-powered text processing and 94% reduction in token usage. Enables saving, searching, and managing documents and highlights through natural language with advanced content controls and spaced repetition learning.

  1. 🚀 What This Is
    1. ✨ Key Features
      1. 📚 Enhanced Reader Management
      2. 🎯 Complete Highlights Ecosystem
      3. ⚡ Production Excellence
    2. 🛠️ Installation
      1. Option 1: NPX - No Installation Required! (Recommended)
      2. Option 2: Global NPM Installation
      3. Option 3: From Source
    3. 🔧 Configuration
      1. With Any MCP-Compatible Tool
    4. 📖 Available Tools (13 Total)
      1. 📚 Reader Tools (6) - Enhanced
      2. 🎯 Highlights Tools (7) - New
    5. 🎯 Context Optimization
      1. 🧠 AI-Powered Features
        1. Intelligent Word Segmentation
        2. Smart Content Processing
        3. Advanced Search Algorithm
      2. 📊 Technical Architecture
        1. Dual API Client System
        2. Context-Efficient Design
        3. Production Ready
      3. ⚙️ API Coverage
        1. Readwise Reader API (v3)
        2. Readwise Highlights API (v2)
      4. 🔐 Authentication & Security
        1. 📈 Rate Limits
          1. 🚀 Usage Examples
            1. Smart Content Extraction
            2. Comprehensive Search
            3. Daily Learning Workflow
          2. 📦 Dependencies
            1. 🔄 Migration from Basic Reader MCP
              1. 🌟 Why This MCP?
                1. vs. Official Readwise MCP
                2. vs. Basic Reader MCPs
              2. 📄 License
                1. 🙏 Acknowledgments

                  Related MCP Servers

                  • A
                    security
                    F
                    license
                    A
                    quality
                    An MCP server that provides a tool to extract text content from local PDF files, supporting both standard PDF reading and OCR capabilities with optional page selection.
                    Last updated -
                    1
                    17
                    Python
                    • Apple
                  • -
                    security
                    F
                    license
                    -
                    quality
                    A custom MCP server that allows storage, retrieval, and management of text-based information with natural language commands and keyword detection.
                    Last updated -
                    TypeScript
                    • Linux
                    • Apple
                  • -
                    security
                    A
                    license
                    -
                    quality
                    Enables access and interaction with your Readwise library, allowing you to retrieve and search highlights, books, and documents through natural language queries when using Claude or other MCP-compatible assistants.
                    Last updated -
                    22
                    TypeScript
                    MIT License
                  • A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that connects MCP-compatible clients like Claude and VS Code to your Readwise Reader library, allowing them to list, retrieve, and update documents in your personal knowledge repository.
                    Last updated -
                    1
                    9
                    Python
                    MIT License

                  View all related MCP servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/arnaldo-delisio/readwise-mcp-enhanced'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server