Readwise MCP Enhanced

🚀 Readwise MCP Enhanced

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

🚀 Quick Start

This is the first unified MCP that combines the Complete Readwise Reader API, Full Readwise Highlights API, AI-Powered Text Processing, Context Optimization, and Smart Content Controls. It's equivalent to the official Readwise MCP but more efficient and feature-complete, and is compatible with all MCP clients.

✨ Features

📚 Enhanced Reader Management

• Smart Content Extraction: Supports pagination, keyword filtering, and length limits.
• AI-Powered Text Processing: Automatically fixes merged words through word segmentation.
• Performance Controls: Includes built-in warnings and guidance for expensive operations.
• Flexible Filtering: Allows filtering by location, category, tags, dates, and custom criteria.

🎯 Complete Highlights Ecosystem

• Daily Reviews: Implements a spaced repetition learning system.
• Advanced Search: Enables field-specific queries with relevance scoring.
• Book Management: Provides full metadata with highlight counts and filtering.
• Export & Backup: Supports bulk highlight analysis and incremental sync.
• Manual Creation: Allows adding highlights with full metadata support.

⚡ Production Excellence

• Context Optimized: Reduces token usage by 94% (from 25,600 to 1,600 tokens).
• Dual API Architecture: Seamlessly integrates the v2 (highlights) and v3 (Reader) APIs.
• Unlimited Results: Offers efficient data per item without artificial limits.
• MCP Protocol Compliant: Ensures proper logging, error handling, and rate limiting.

📦 Installation

Option 1: NPX - No Installation Required! (Recommended)

No installation is 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

💻 Usage Examples

[Basic Usage]

Smart Content Extraction

// Paginate through large document
readwise_list_documents({
  withFullContent: true,
  contentMaxLength: 5000,
  contentStartOffset: 0,
  contentFilterKeywords: ["machine learning", "AI"]
})

Comprehensive Search

// 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
})

📚 Documentation

📖 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
}

• 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.
• readwise_topic_search: Enhanced with AI-powered text processing.

🎯 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: Significantly reduces token usage while maintaining full functionality. | Tool | Before | After | Savings | |------|--------|-------|---------| | List Highlights (32 items) | ~25,600 tokens | ~1,600 tokens | 94% | | Daily Review (5 items) | ~5,000 tokens | ~400 tokens | 92% | | List Books (10 items) | ~8,000 tokens | ~600 tokens | 93% |
• Optimized Fields: Only includes essential fields for highlights, books, and search.

🧠 AI-Powered Features

• Intelligent Word Segmentation: Automatically fixes common text extraction issues.
• Smart Content Processing: Implements sentence-based chunking, distributed keyword filtering, and context-aware text extraction.
• Advanced Search Algorithm: Supports multi-field search with relevance scoring, export-based comprehensive search, and field-specific filtering.

🔧 Technical Details

Technical Architecture

• Dual API Client System: Seamlessly switches between the v2 (Highlights) and v3 (Reader) APIs.

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

• Context-Efficient Design: Offers unlimited results with minimal data per item, LLM-optimized responses, and structured JSON.
• Production Ready: Adheres to the ES Module standard, is MCP protocol compliant, and has comprehensive rate limiting.

API Coverage

• Readwise Reader API (v3): Covers document management, tag handling, content extraction, and search.
• Readwise Highlights API (v2): Covers highlight management, book management, daily review, and advanced search.

Authentication & Security

• Single Token: Uses one Readwise token for both APIs.
• Environment Variable: Securely stores the token via READWISE_TOKEN.
• No Token Exposure: Ensures the token is not exposed through MCP clients or tools interface.

Rate Limits

• Reader API: Has a default limit of 20 requests per minute and 50 requests per minute for CREATE/UPDATE operations.
• Highlights API: Follows the standard Readwise limits with automatic retry-after handling.

📄 License

This project is licensed under the MIT license.

🙏 Acknowledgments

This project is built upon the foundation of edricgan/Readwise-Reader-MCP with significant enhancements, evolving from basic document management to a comprehensive, production-ready Readwise platform.