Provides comprehensive integration with Readwise Reader for document management (save, list, update, delete documents and tags) and full Readwise highlights functionality including daily reviews, advanced search, book management, highlight creation, and bulk export capabilities.
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
Option 3: From Source
🔧 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):
Option B - If installed globally via npm:
Option C - If installed from source:
- macOS:
- 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.
readwise_list_documents
⭐ Enhanced with Smart Content Controls
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:
readwise_get_daily_review
Get your spaced repetition highlights:
readwise_search_highlights
⭐ Advanced search with field-specific queries:
readwise_list_books
Get books with highlight metadata:
readwise_get_book_highlights
Get all highlights from a specific book:
readwise_export_highlights
Bulk export for analysis and backup:
readwise_create_highlight
Manually add highlights with metadata:
🎯 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
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
Comprehensive Search
Daily Learning Workflow
📦 Dependencies
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. 🚀
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
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.
- 🚀 What This Is
- ✨ Key Features
- 🛠️ Installation
- 🔧 Configuration
- 📖 Available Tools (13 Total)
- 🎯 Context Optimization
- 🧠 AI-Powered Features
- 📊 Technical Architecture
- ⚙️ API Coverage
- 🔐 Authentication & Security
- 📈 Rate Limits
- 🚀 Usage Examples
- 📦 Dependencies
- 🔄 Migration from Basic Reader MCP
- 🌟 Why This MCP?
- 📄 License
- 🙏 Acknowledgments
Related MCP Servers
- AsecurityFlicenseAqualityAn 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 -117Python
- -securityFlicense-qualityA custom MCP server that allows storage, retrieval, and management of text-based information with natural language commands and keyword detection.Last updated -TypeScript
- -securityAlicense-qualityEnables 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 -22TypeScriptMIT License
- AsecurityAlicenseAqualityA 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 -19PythonMIT License