Readwise Reader MCP Server

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.

Features

• 🔐 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

Available Tools

1. readwise_authenticate - Authenticate with Readwise Reader API

2. readwise_save_document - Save a new document (URL or HTML content)

3. readwise_list_documents - List documents with filters

4. readwise_update_document - Update document metadata

5. readwise_delete_document - Delete a document

6. readwise_list_tags - List all available tags

7. readwise_get_document_content - Get full content of a specific document

Quick Start

Prerequisites

1. Python 3.9+ installed

2. Readwise Account with Reader access

3. Access Token from https://readwise.io/access_token

Installation

# Clone the repository
git clone <repository-url>
cd readwise-reader-mcp

# Install the package
pip install -e .

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and add your Readwise access token:

READWISE_ACCESS_TOKEN=your_token_here

Running the Server

Local Development

# Run with default settings (port 8000)
readwise-reader-mcp

# Run on custom port
readwise-reader-mcp --port 9000

# Show help
readwise-reader-mcp --help

Using Docker

Build 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-mcp

Docker Compose

version: '3.8'
services:
  readwise-reader-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - READWISE_ACCESS_TOKEN=your_token_here
      - LOG_LEVEL=INFO

Integration with Claude Desktop

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

API Usage Examples

Save a Document

# 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 Documents

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

Update Document

readwise_update_document({
    "document_id": "doc_id_here",
    "title": "New Title",
    "location": "archive"
})

Document Locations

• new - New/Inbox (default for saved documents)

• later - Read Later list

• shortlist - Shortlist

• archive - Archived documents

Document Categories

• 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

Rate Limits

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.

Error Handling

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

Development

Setup Development Environment

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Lint code
ruff check src/

Project Structure

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

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• Readwise API Documentation: https://readwise.io/reader_api

• MCP Documentation: Model Context Protocol

Changelog

0.1.0

• Initial release

• Basic document management tools

• HTTP transport support

• Docker containerization

• Authentication and error handling