readwise-mcp-http-server

CaseyRo/readwise-mcp-http-server

3.2

If you are the rightful owner of readwise-mcp-http-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Readwise MCP HTTP Server is a Node.js server that provides MCP access to Readwise highlights and documents over HTTP.

Tools
1
Resources
0
Prompts
0

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

Option 1: Local Installation

  1. Install dependencies:
npm install
  1. Create environment file:
cp .env.example .env
  1. Add your Readwise access token to .env:
ACCESS_TOKEN=your_readwise_access_token_here
PORT=3000

Option 2: Docker Installation (Recommended)

  1. Create environment file:
cp .env.example .env
  1. Configure your environment variables in .env:
ACCESS_TOKEN=your_readwise_access_token_here
PORT=3000
NODE_ENV=production
DEBUG=false
BASE_URL=https://readwise.io
  1. Run with Docker Compose:
# Production
docker-compose up -d

# Development (with hot reloading)
docker-compose -f docker-compose.dev.yml up -d

For detailed Docker instructions, see .

Usage

Development

npm run dev

Production

npm run build
npm start

Watch Mode

npm run watch

Docker Usage

Production Mode
# Start the production container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
Development Mode (with hot reloading)
# Start the development container
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop the service
docker-compose -f docker-compose.dev.yml down

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