readwise-reader-mcp

README.md
# 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](https://readwise.io/access_token)

### Installation

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

# Install the package
pip install -e .
```

### Configuration

1. Copy the example environment file:
```bash
cp .env.example .env
```

2. Edit `.env` and add your Readwise access token:
```bash
READWISE_ACCESS_TOKEN=your_token_here
```

### Running the Server

#### Local Development
```bash
# 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:
```bash
# 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
```yaml
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:

```json
{
  "mcpServers": {
    "readwise-reader": {
      "command": "readwise-reader-mcp",
      "args": ["--port", "8000"],
      "env": {
        "READWISE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

Or use WebSocket connection:
```json
{
  "mcpServers": {
    "readwise-reader": {
      "command": "ws://localhost:8000/ws"
    }
  }
}
```

## API Usage Examples

### Save a Document
```python
# 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
```python
# 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
```python
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:

```json
{
  "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

```bash
# 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](https://github.com/yourusername/readwise-reader-mcp/issues)
- **Readwise API Documentation**: [https://readwise.io/reader_api](https://readwise.io/reader_api)
- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)

## Changelog

### 0.1.0
- Initial release
- Basic document management tools
- HTTP transport support
- Docker containerization
- Authentication and error handling
This server cannot be deployed
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Maintenance

ActivityInactive
ResponsivenessNo issues
Resources

GitHub Repository
Need Help?
Related Servers