Readwise MCP Enhanced

npm version npm downloads

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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

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.

Tools

View all tools

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.

Related MCP Servers

PDF Extraction MCP Server
xraywu
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
18
Zanny's Persistent Memory Manager
-
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.
Readwise MCP Server
IAmAlexander
-
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 -
21
MIT License
Reader MCP Server
xinthink
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
10
MIT License

View all related MCP servers