npm package: @hyphagroup/readwise-mcp
Description: MCP server for Readwise - access highlights, documents, and books via Model Context Protocol
Author: HyphaGroup
Latest version: 0.1.1

# @hyphagroup/readwise-mcp

MCP server for Readwise - access your highlights, documents, and books via Model Context Protocol.

## Features

- **Unified Search** - Search across both highlights and Reader documents with filters
- **Reader API (v3)** - Save, list, update, and delete documents
- **Highlights API (v2)** - List, create, update, delete, and export highlights
- **Highlight Tags** - List, add, and remove tags on highlights
- **Books & Daily Review** - Access your library and spaced repetition reviews
- **Debug Logging** - Optional verbose logging for troubleshooting

## Installation

### Global Install (Recommended)

```bash
npm install -g @hyphagroup/readwise-mcp
```

Then run:

```bash
readwise-mcp
```

### Via npx

```bash
npx -y -p @hyphagroup/readwise-mcp readwise-mcp
```

## Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `READWISE_API_KEY` | Your Readwise access token. Get it at https://readwise.io/access_token | Yes |
| `READWISE_DEBUG` | Set to `1` for verbose logging to stderr | No |
| `READWISE_DEBUG_LOG` | Path to write debug logs to a file | No |

### Factory AI / Droid

Add to `~/.factory/mcp.json` or `.factory/mcp.json`:

```json
{
  "mcpServers": {
    "readwise": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@hyphagroup/readwise-mcp", "readwise-mcp"],
      "env": {
        "READWISE_API_KEY": "your_token_here"
      }
    }
  }
}
```

Or with global install:

```json
{
  "mcpServers": {
    "readwise": {
      "type": "stdio",
      "command": "readwise-mcp",
      "args": [],
      "env": {
        "READWISE_API_KEY": "your_token_here"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "readwise": {
      "command": "npx",
      "args": ["-y", "-p", "@hyphagroup/readwise-mcp", "readwise-mcp"],
      "env": {
        "READWISE_API_KEY": "your_token_here"
      }
    }
  }
}
```

## Available Tools (18)

### Search
- `readwise_search` - Search across highlights and documents with filters (tags, author, date range, hasNote, sorting)

### Reader Documents (6)
- `readwise_document_list` - List documents with filters (location, category, date)
- `readwise_document_save` - Save a new document by URL or HTML
- `readwise_document_update` - Update document metadata
- `readwise_document_delete` - Delete a document
- `readwise_document_get` - Get document with full HTML content
- `readwise_document_tag_list` - List all tags in Reader

### Highlights (11)
- `readwise_highlight_list` - List highlights with filters
- `readwise_highlight_create` - Create a new highlight
- `readwise_highlight_export` - Bulk export all highlights
- `readwise_highlight_update` - Update highlight text, note, color, or location
- `readwise_highlight_delete` - Delete a highlight (requires confirmation)
- `readwise_highlight_source_list` - List books/articles/sources in your library
- `readwise_highlight_source_get` - Get detailed source information
- `readwise_highlight_review` - Get your daily review highlights
- `readwise_highlight_tag_list` - List tags on a specific highlight
- `readwise_highlight_tag_add` - Add a tag to a highlight
- `readwise_highlight_tag_remove` - Remove a tag from a highlight

## Categories

Reader documents use these categories: `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet`, `video`

## Debugging

Enable verbose logging:

```bash
READWISE_API_KEY=xxx READWISE_DEBUG=1 readwise-mcp
```

Write logs to a file (useful when running via MCP client):

```bash
READWISE_API_KEY=xxx READWISE_DEBUG=1 READWISE_DEBUG_LOG=/tmp/readwise-mcp.log readwise-mcp
```

## License

MIT