Readwise MCP Enhanced

How to use

To use this MCP server, connect it to a compatible MCP client (such as Claude Desktop or Continue IDE) using an MCP configuration that points to the provided server commands. Your client will communicate with the server to save, list, search, and manage documents, highlights, and daily reviews through the unified API surface. Use the client’s standard MCP workflow to: add documents from Readwise Reader, fetch and search highlights, run daily reviews, and export or back up your data. Ensure your MCP client is configured with your Readwise access token and the correct server command and environment variables.

How to install

Prerequisites: Node.js (version 16.x or newer) and npm must be available on your system. You also need a Readwise access token to access your data.

# Option 1: Run without installation (recommended)
# Your MCP client will download and run the package on demand using npx

# Option 2: Global npm installation
npm install -g readwise-mcp-enhanced

# Option 3: Install from source
# 1) Clone the repository
git clone https://github.com/arnaldo-delisio/readwise-mcp-enhanced.git
# 2) Enter the project directory
cd readwise-mcp-enhanced
# 3) Install dependencies
npm install
# 4) Build the project
npm run build
```
"}]} ,{

Note: The project provides multiple ways to run the MCP server. If you prefer a rapid start, use the NPX option described below and provide your Readwise token to authorize access to your data.

Configuration

Get your Readwise token and configure your MCP client to start the Readwise MCP Enhanced server. The token is required for authentication and must be supplied through environment variables in your MCP client configuration.

Option A - Using NPX (Recommended):

```json
{
  "mcpServers": {
    "readwise_mcp": {
      "command": "npx",
      "args": ["readwise-mcp-enhanced"],
      "env": {
        "READWISE_TOKEN": "your_readwise_access_token_here"
      }
    }
  }
}
```

Option B - If installed globally via npm:

```json
{
  "mcpServers": {
    "readwise_mcp": {
      "command": "readwise-mcp-enhanced",
      "env": {
        "READWISE_TOKEN": "your_readwise_access_token_here"
      }
    }
  }
}
```

Option C - If installed from source (after building):

```json
{
  "mcpServers": {
    "readwise_mcp": {
      "command": "node",
      "args": ["/path/to/readwise-mcp-enhanced/dist/index.js"],
      "env": {
        "READWISE_TOKEN": "your_readwise_access_token_here"
      }
    }
  }
}
```

Restart your MCP client after adding the configuration to apply the new server.

Security, rate limits, and notes

Authentication uses a single Readwise token for both APIs. The token must be stored securely in your MCP client environment variable as READWISE_TOKEN and should never be exposed through the MCP client interface.

Rate limits are enforced per API with sensible retry behavior. If a 429 is returned, the client should honor the Retry-After header and retry accordingly. This helps protect against overload during peak usage.

The server is designed to be production-ready, with context-optimized responses, unlimited results per request, and robust logging and error handling in accordance with MCP protocol requirements.

Usage examples

Here are common usage patterns you can perform with your MCP client after connecting the server.

// Smart content extraction example: paginate through a large document
readwise_list_documents({
  withFullContent: true,
  contentMaxLength: 5000,
  contentStartOffset: 0,
  contentFilterKeywords: ["machine learning", "AI"]
})

// Comprehensive search across documents and highlights
readwise_search_highlights({
  textQuery: "productivity habits",
  fieldQueries: [
    { field: "document_author", searchTerm: "James Clear" }
  ],
  limit: 10
})

// Daily learning workflow: fetch daily review and search related highlights
readwise_get_daily_review()
readwise_search_highlights({
  textQuery: "from daily review topics",
  limit: 20
})

readwise_save_document

Save documents with full metadata control including URL, tags, location, and category.

readwise_list_documents

List documents with smart content controls, including full content extraction options and keyword filtering.

readwise_update_document

Update document metadata such as title, author, summary, and location.

readwise_delete_document

Remove documents from your Reader library.

readwise_list_tags

Retrieve all document tags.

readwise_topic_search

AI-powered topic search across titles, summaries, notes, and tags using advanced text processing.

readwise_list_highlights

List highlights with advanced filtering and pagination.

readwise_get_daily_review

Get your spaced repetition daily review highlights.

readwise_search_highlights

Perform field-specific search across highlights with relevance scoring.

readwise_list_books

List books with metadata and highlighting counts.

readwise_get_book_highlights

Retrieve all highlights for a specific book.

readwise_export_highlights

Bulk export highlights for analysis and backup.

readwise_create_highlight

Manually add highlights with full metadata.