MCP 服务器

readwise-reader-mcp

Enables integration with Readwise Reader API to save, retrieve, update, and manage documents, tags, and filtering in your Readwise Reader account.

README

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

Available Tools

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

Quick Start

Prerequisites

Python 3.9+ installed
Readwise Account with Reader access
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

Copy the example environment file:

cp .env.example .env

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

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