Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@readwise-reader-mcp save https://example.com/article to my read later"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for integrating with Readwise Reader API. This server provides tools for saving, retrieving, updating, and managing documents in your Readwise Reader account.
š Authentication: Secure token-based authentication with Readwise Reader
š Document Management: Save, list, update, and delete documents
š·ļø Tag Management: List and organize your tags
š Advanced Filtering: Filter documents by location, category, tags, and dates
š HTTP Transport: Streamable HTTP server for easy integration
š³ Docker Support: Containerized deployment ready
Related MCP server: Readwise Reader MCP Server
readwise_authenticate - Authenticate with Readwise Reader API
readwise_save_document - Save a new document (URL or HTML content)
readwise_list_documents - List documents with filters
readwise_update_document - Update document metadata
readwise_delete_document - Delete a document
readwise_list_tags - List all available tags
readwise_get_document_content - Get full content of a specific document
Python 3.9+ installed
Readwise Account with Reader access
Access Token from https://readwise.io/access_token
# Clone the repository
git clone <repository-url>
cd readwise-reader-mcp
# Install the package
pip install -e .Copy the example environment file:
cp .env.example .envEdit .env and add your Readwise access token:
READWISE_ACCESS_TOKEN=your_token_here# Run with default settings (port 8000)
readwise-reader-mcp
# Run on custom port
readwise-reader-mcp --port 9000
# Show help
readwise-reader-mcp --helpBuild and run with Docker:
# Build the image
docker build -t readwise-reader-mcp .
# Run with environment file
docker run -p 8000:8000 --env-file .env readwise-reader-mcp
# Or run with inline environment variable
docker run -p 8000:8000 -e READWISE_ACCESS_TOKEN=your_token readwise-reader-mcpversion: '3.8'
services:
readwise-reader-mcp:
build: .
ports:
- "8000:8000"
environment:
- READWISE_ACCESS_TOKEN=your_token_here
- LOG_LEVEL=INFOAdd this configuration to your Claude Desktop settings:
{
"mcpServers": {
"readwise-reader": {
"command": "readwise-reader-mcp",
"args": ["--port", "8000"],
"env": {
"READWISE_ACCESS_TOKEN": "your_token_here"
}
}
}
}Or use WebSocket connection:
{
"mcpServers": {
"readwise-reader": {
"command": "ws://localhost:8000/ws"
}
}
}# Save a web page by URL
readwise_save_document({
"url": "https://example.com/article",
"title": "Interesting Article",
"tags": ["tech", "ai"],
"location": "later"
})
# Save HTML content directly
readwise_save_document({
"html": "<html><body><h1>My Article</h1>...</body></html>",
"title": "Custom Content",
"category": "article"
})# List recent documents
readwise_list_documents()
# Filter by location
readwise_list_documents({
"location": "archive",
"category": "article"
})
# Get documents updated after a date
readwise_list_documents({
"updated_after": "2024-01-01T00:00:00Z"
})readwise_update_document({
"document_id": "doc_id_here",
"title": "New Title",
"location": "archive"
})new - New/Inbox (default for saved documents)
later - Read Later list
shortlist - Shortlist
archive - Archived documents
article - Web articles
email - Email content
rss - RSS feed items
highlight - Highlights
note - Personal notes
pdf - PDF documents
epub - EPUB books
tweet - Twitter content
video - Video content
The Readwise Reader API has the following rate limits:
General requests: 20 requests per minute
Document saves/updates: 50 requests per minute
The client automatically handles rate limit errors and includes appropriate retry information.
The server provides detailed error responses:
{
"success": false,
"error": "Authentication failed: Invalid token"
}Common errors:
Authentication errors: Invalid or expired token
Rate limiting: Too many requests
Validation errors: Missing required parameters
API errors: Readwise service issues
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black src/
# Lint code
ruff check src/readwise-reader-mcp/
āāā src/
ā āāā readwise_reader_mcp/
ā āāā __init__.py
ā āāā client.py # Readwise API client
ā āāā models.py # Pydantic models
ā āāā server.py # FastMCP server
āāā tests/ # Test files
āāā Dockerfile # Container configuration
āāā pyproject.toml # Project configuration
āāā .env.example # Environment template
āāā README.mdFork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request
MIT License - see LICENSE file for details.
Issues: GitHub Issues
Readwise API Documentation: https://readwise.io/reader_api
MCP Documentation: Model Context Protocol
Initial release
Basic document management tools
HTTP transport support
Docker containerization
Authentication and error handling
This server cannot be deployed
Search and organize your reading library of highlights, saved articles, notes and tags.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
Save, search and organize bookmarks, highlights, feeds and knowledge cards in a Linkflare library.
Ingest, manage, and retrieve documents for RAG-powered AI applications
