Readwise Pet for OpenPets

Access your Readwise highlights and reading content through the official Readwise MCP server.

Version: 1.0.1

Overview

This pet integrates with Readwise using the official Model Context Protocol (MCP) server (@readwise/readwise-mcp). It provides tools for:

• Search highlights using full-text and semantic/vector search
• Access daily review highlights
• Query by metadata (author, book title, tags, notes)
• List books and articles in your library

Setup

1. Get Your Access Token

1. Visit https://readwise.io/access_token
2. Log into your Readwise account
3. Copy your access token

2. Configure Environment

cp .env.example .env

Edit .env and add your token:

READWISE_ACCESS_TOKEN=your_token_here

3. Test Connection

opencode run "test readwise connection"

MCP Tool Generation

This pet uses auto-generated MCP tools from the official Readwise MCP server. The mcp.ts file contains the generated tool definitions.

To regenerate with the latest tools from the MCP server:

cd pets/readwise
pets generate-mcp --verbose

Note: You need a valid READWISE_ACCESS_TOKEN to generate tools.

Usage Examples

Search Highlights

# Search for specific topics
opencode run "search my readwise highlights for 'productivity hacks'"

# Find by author
opencode run "search readwise by author 'Cal Newport'"

# Semantic/vector search
opencode run "search my readwise highlights for 'deep work concepts' using vector search"

# Search by tag
opencode run "search readwise by tag 'philosophy'"

Daily Review

# Get today's review highlights
opencode run "get my daily review highlights"

# Get specific number of review highlights
opencode run "get my daily review highlights with limit 10"

Browse Library

# List books
opencode run "list my readwise books"

# List articles
opencode run "list my readwise articles"

# Get account info
opencode run "get readwise account info"

Available Tools

MCP Tools (Auto-Generated)

| Tool | Description | |------|-------------| | readwise-search-highlights | Search highlights with full-text or vector search | | readwise-get-highlight | Get a specific highlight by ID | | readwise-list-highlights | List highlights with filters | | readwise-get-daily-review | Get daily review highlights | | readwise-list-books | List books/articles in your library | | readwise-search-by-author | Search highlights by author | | readwise-search-by-tag | Search highlights by tag |

Custom Tools

| Tool | Description | |------|-------------| | readwise-test-connection | Test connection and verify token | | readwise-get-account-info | Get account statistics |

Technical Details

MCP Server

• Package: @readwise/readwise-mcp@latest
• Runtime: Node.js (via npx)
• Authentication: Token-based via ACCESS_TOKEN env var
• Base URL: https://readwise.io/api/v2/

APIs Used

• Readwise API v2 (highlights, books, daily review)
• Search endpoints with vector embedding support

Rate Limits

• Default: 240 requests/minute
• List endpoints: 20 requests/minute
• Retry-After header provided for 429 responses

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | READWISE_ACCESS_TOKEN | Yes | Your Readwise access token |

package.json

{
  "mcpServer": {
    "npmPackage": "@readwise/readwise-mcp@latest",
    "name": "readwise",
    "url": "https://github.com/readwiseio/readwise-mcp"
  }
}

Regenerating MCP Tools

When the Readwise MCP server updates with new tools:

cd pets/readwise

# Preview what will be generated
pets generate-mcp --dry-run --verbose

# Generate updated tools
pets generate-mcp

Troubleshooting

Connection Issues

If you see connection errors:

1. Verify token: Ensure your READWISE_ACCESS_TOKEN is set correctly
2. Check token validity: Visit https://readwise.io/access_token to regenerate if needed
3. Test auth endpoint: The token should work with GET https://readwise.io/api/v2/auth/ (returns 204)

MCP Tool Generation Fails

If pets generate-mcp fails:

1. Verify your READWISE_ACCESS_TOKEN is set and valid
2. Check you have network access to npm and Readwise API
3. Try running with verbose output: pets generate-mcp --verbose

Rate Limiting

If you hit rate limits:

1. Wait for the Retry-After period (shown in error messages)
2. The MCP client handles rate limiting automatically
3. Consider reducing the frequency of requests

Search Not Working

If searches return no results:

1. Ensure you have highlights in your Readwise account
2. Try broader search terms first
3. Check that your account sync is up to date

Architecture

┌─────────────────────────────────────────┐
│         OpenCode/OpenPets              │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │      Readwise Plugin            │   │
│  │                                 │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │    MCP Tools (mcp.ts)   │   │   │
│  │  │  - Search highlights    │   │   │
│  │  │  - Daily review         │   │   │
│  │  │  - List books           │   │   │
│  │  └─────────────────────────┘   │   │
│  │                                 │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │   Custom Tools          │   │   │
│  │  │  - Test connection      │   │   │
│  │  │  - Account info         │   │   │
│  │  └─────────────────────────┘   │   │
│  └─────────────────────────────────┘   │
│                   │                     │
│                   │ MCP Protocol        │
│                   ▼                     │
│  ┌─────────────────────────────────┐   │
│  │  @readwise/readwise-mcp         │   │
│  │  (npx - runs locally)          │   │
│  └─────────────────────────────────┘   │
│                   │                     │
│                   │ HTTPS               │
│                   ▼                     │
│  ┌─────────────────────────────────┐   │
│  │      Readwise API v2           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Official Resources

• Readwise API Docs: https://readwise.io/api_deets
• Reader API Docs: https://readwise.io/reader_api
• MCP Setup Guide: https://docs.readwise.io/readwise/guides/mcp
• Access Token: https://readwise.io/access_token
• MCP Server Repo: https://github.com/readwiseio/readwise-mcp

Alternative MCP Clients

The official Readwise MCP server also works with:

• Claude Desktop: Native MCP support
• Raycast: Via MCP extension
• ChatGPT: Pro/Team/Enterprise plans (OAuth connector)

See the official docs for setup instructions.

Development

File Structure

pets/readwise/
├── index.ts              # Main plugin entry point
├── mcp.ts                # Auto-generated MCP tools
├── package.json          # Pet configuration with mcpServer
├── opencode.json         # OpenCode loader config
├── .env.example          # Environment variable template
└── README.md             # This file

Testing

# Test connection
bun test:connection

# Quick start example
bun quickstart

# Test with specific query
bun test:pet readwise --query "search for 'habits'"

# Interactive mode
bun test:pet readwise --interactive

License

MIT - See parent repository for details.

Support

• Readwise Support: [email protected]
• Documentation: https://docs.readwise.io
• Community: https://reddit.com/r/readwise