readwise-mcp-enhanced

v1.0.1

Published

7 months ago

Enhanced MCP server unifying Readwise Reader + Highlights with AI-powered text processing and context optimization

0High
0Medium
0Low

arnaldo-delisio

readwise mcp model-context-protocol claude ai highlights reader knowledge-management typescript

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

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

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

Get your Readwise token: https://readwise.io/access_token

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

Option A - Using npx (Recommended):

{
  "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"
      }
    }
  }
}

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

`readwise_topic_search`

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

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

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:

whatyou → what you
fromdissatisfaction → from dissatisfaction
timeago → time 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"]
})

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

📦 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. 🚀