Skip to main content
Glama

Readwise MCP HTTP Server

by CaseyRo
OverviewInspectNewSchemaRelated ServersScore
TypeScript
Remote

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 DOCKER.md.

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Related Resources

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 -
    22
    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
    • Apple
    • Linux

View all related MCP servers

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CaseyRo/readwise-mcp-http-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server