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
- 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
Option 2: Docker Installation (Recommended)
- Create environment file:
cp .env.example .env
- 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
- 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 searchfull_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 documentdocument_title- Title of the source documenthighlight_note- Notes you've added to highlightshighlight_plaintext- The actual highlighted texthighlight_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 tokenPORT(optional): Server port (default: 3000)BASE_URL(optional): Readwise API base URL (default: https://readwise.io)DEBUG(optional): Enable debug logging (set totruefor detailed logs)NODE_ENV(optional): Set todevelopmentto 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 JavaScriptnpm run dev- Run in development mode with hot reloadnpm run watch- Watch for changes and restartnpm start- Run compiled JavaScript
License
MIT