Skip to main content
Glama
ivanlee1999

readwise-reader-mcp

by ivanlee1999
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

  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

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

Changelog

0.1.0

  • Initial release

  • Basic document management tools

  • HTTP transport support

  • Docker containerization

  • Authentication and error handling

This server cannot be installed

-
license - not tested
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ivanlee1999/readwise-reader-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server