Readwise MCP HTTP Server

A Node.js HTTP server that provides proper MCP (Model Context Protocol) over HTTP access to Readwise highlights and documents, using the official @readwise/readwise-mcp module.

Features

🔍 Search Highlights: Vector and full-text search through your Readwise highlights (using official Readwise MCP module)
📡 Streaming Responses: Real-time streaming of search results
🏥 Health Checks: Server health monitoring
🔄 Automatic Retries: Built-in retry logic for API failures
🛡️ CORS Support: Cross-origin request support
🔍 Comprehensive Debugging: Detailed logging for development and troubleshooting
🌐 Network Access: Accessible from all network interfaces
✅ Official Module: Uses the same tool implementation as the official Readwise MCP module

Installation

Install dependencies:

npm install

Create environment file:

cp .env.example .env

Add your Readwise access token to .env:

ACCESS_TOKEN=your_readwise_access_token_here
PORT=3000

Usage

Development

npm run dev

Production

npm run build
npm start

Watch Mode

npm run watch

Debug Mode

Enable detailed debugging by setting the DEBUG environment variable:

# Enable debug mode
DEBUG=true npm run dev

# Or set in .env file
DEBUG=true

Debug mode provides detailed logging for:

Connection attempts
Request/response details
Tool execution steps
API calls to Readwise
Error details

API Endpoints

MCP Protocol Endpoint

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_readwise_highlights",
    "arguments": {
      "vector_search_term": "machine learning"
    }
  }
}

MCP Streaming Endpoint

POST /mcp/stream
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_readwise_highlights",
    "arguments": {
      "vector_search_term": "machine learning"
    }
  }
}

Server Info

GET /mcp/info

Health Check

GET /health

Available Tools

The server provides the same tools as the official Readwise MCP module:

`search_readwise_highlights`

Search through your Readwise highlights using vector search and full-text queries.

Parameters:

vector_search_term (required): Semantic search term for vector search
full_text_queries (required): Array of field-specific searches

Note: Both parameters are required. Empty arguments will result in a validation error.

Search Field Types:

document_author - Author of the source document
document_title - Title of the source document
highlight_note - Notes you've added to highlights
highlight_plaintext - The actual highlighted text
highlight_tags - Tags you've applied to highlights

Example Usage

Initialize MCP Connection

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
  }'

List Available Tools

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Search Highlights (MCP Protocol)

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_readwise_highlights",
      "arguments": {
        "vector_search_term": "machine learning"
      }
    }
  }'

Stream Search Results (MCP Protocol)

curl -X POST http://localhost:3000/mcp/stream \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "search_readwise_highlights",
      "arguments": {
        "vector_search_term": "machine learning",
        "full_text_queries": [
          {
            "field_name": "highlight_plaintext",
            "search_term": "artificial intelligence"
          }
        ]
      }
    }
  }'

Invalid Arguments Example

# This will return an error because both parameters are required
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "search_readwise_highlights",
      "arguments": {}
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32602,
    "message": "Invalid arguments: Required, Required"
  }
}

Environment Variables

ACCESS_TOKEN (required): Your Readwise access token
PORT (optional): Server port (default: 3000)
BASE_URL (optional): Readwise API base URL (default: https://readwise.io)
DEBUG (optional): Enable debug logging (set to true for detailed logs)
NODE_ENV (optional): Set to development to enable debug mode automatically

Network Connectivity

The servers are configured to bind to all network interfaces (0.0.0.0), making them accessible from:

Localhost: http://localhost:3000
Local Network: http://YOUR_IP_ADDRESS:3000
Docker: http://host.docker.internal:3000

To find your server's IP address:

# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Windows
ipconfig | findstr "IPv4"

Error Handling

The server includes comprehensive error handling:

Input validation using Zod schemas
Automatic retry logic for failed API calls
Proper HTTP status codes
Detailed error messages
Comprehensive logging for debugging

Debugging

The server provides extensive debugging capabilities:

Debug Logs

When debug mode is enabled, you'll see detailed logs for:

Connection tracking: Every incoming request with IP and user agent
Request processing: Step-by-step MCP request handling
Tool execution: Detailed tool call processing
API interactions: Readwise API calls and responses
Streaming: Real-time streaming progress
Error details: Full error stack traces and context

Debug Output Example

[2024-01-15T10:30:00.000Z] ℹ️  INFO: Initializing Readwise MCP HTTP Server
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Port: 3000, Debug: true, NodeEnv: development
[2024-01-15T10:30:00.000Z] 🔗 CONNECTION: POST /mcp from 127.0.0.1
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Request body: {"jsonrpc":"2.0","id":1,"method":"tools/call"...}
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Processing MCP method: tools/call
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Tool call requested: search_readwise_highlights
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Calling Readwise API: {"vector_search_term":"machine learning"}
[2024-01-15T10:30:00.000Z] 🔍 DEBUG: Readwise API response received: 5 results

Development

Project Structure

src/
  index.ts          # Main server file
dist/               # Compiled JavaScript (generated)
node_modules/       # Dependencies

Scripts

npm run build - Compile TypeScript to JavaScript
npm run dev - Run in development mode with hot reload
npm run watch - Watch for changes and restart
npm start - Run compiled JavaScript

License

MIT

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables searching and accessing Readwise highlights and documents through HTTP endpoints using the Model Context Protocol. Provides vector and full-text search capabilities with streaming responses for retrieving reading highlights and notes.

Related MCP Servers

Readwise MCP Server
IAmAlexander
-
security
A
license
-
quality
Enables access and interaction with your Readwise library, allowing you to retrieve and search highlights, books, and documents through natural language queries when using Claude or other MCP-compatible assistants.
Last updated -
20
MIT License
Kiseki-Labs-Readwise-MCP
kiseki-technologies
-
security
F
license
-
quality
A Model Context Protocol Server that enables language models to access and manipulate Readwise documents and highlights programmatically.
Last updated -
7
Reader MCP Server
xinthink
A
security
A
license
A
quality
A Model Context Protocol server that connects MCP-compatible clients like Claude and VS Code to your Readwise Reader library, allowing them to list, retrieve, and update documents in your personal knowledge repository.
Last updated -
1
10
MIT License
FS-MCP Server
boleyn
-
security
A
license
-
quality
A Model Context Protocol server that provides intelligent file reading and semantic search capabilities across multiple document formats with security-first access controls.
Last updated -
5
MIT License

View all related MCP servers

Readwise MCP HTTP Server