Readwise MCP Server
A Model Context Protocol (MCP) server for accessing and interacting with your Readwise library.
Features
- Access highlights from your Readwise library
- Search for highlights using natural language queries
- Get books and documents from your library
- Seamless integration with Claude and other MCP-compatible assistants
- Enhanced prompt capabilities for highlight analysis
- Transport-aware logging system
- Robust error handling and validation
- MCP protocol compliance with proper request_id handling
- Health check endpoint for monitoring
- Improved setup wizard with API key validation
Project Structure
This repository is organized into the following key directories:
- src/: Main source code for the Readwise MCP server
- test-scripts/: Test scripts and utilities for validating MCP server functionality
- examples/: Example implementations and code samples
- dist/: Compiled JavaScript output (generated)
- scripts/: Utility scripts for development and testing
Installation
Setup
Before using the server, you need to configure your Readwise API key:
You can get your API key from https://readwise.io/access_token.
Usage
CLI
API
Testing with MCP Inspector
The project includes built-in support for testing with the MCP Inspector. You can use either the TypeScript script or the shell script to run the inspector.
Automated Tests
Run the automated test suite that verifies all tools and prompts:
The test suite verifies:
- Server startup and connection
- Tool availability and responses
- Prompt functionality
- Error handling
- Response format compliance
Each test provides detailed output and a summary of passed/failed cases.
Manual Testing
Using the Shell Script
Using the TypeScript Script
Available Options
-t, --transport <type>: Transport type (stdio or sse), default: stdio
-p, --port <number>: Port number for SSE transport, default: 3001
-d, --debug: Enable debug mode
Example Inspector Commands
Test a specific tool:
Test a prompt:
List available tools and prompts:
Testing Without a Readwise API Key
If you don't have a Readwise API key or don't want to use your real API key for testing, you can use the mock testing functionality:
This runs a test script that:
- Creates a mock implementation of the Readwise API
- Sets up the MCP server with this mock API
- Tests various endpoints with sample data
- Verifies server functionality without requiring a real API key
The mock implementation includes:
- Sample books, highlights, and documents
- Simulated network delays for realistic testing
- Error handling testing
Available Tools
- get_highlights: Get highlights from your Readwise library
- get_books: Get books from your Readwise library
- get_documents: Get documents from your Readwise library
- search_highlights: Search for highlights in your Readwise library
Available Prompts
- readwise_highlight: Process highlights from Readwise
- readwise_search: Search and process highlights from Readwise
Recent Improvements
Enhanced MCP Protocol Compliance
- Proper handling of request_id in all responses
- Validation of incoming requests against MCP protocol specifications
- Consistent error response format following MCP guidelines
Improved Setup Experience
- Interactive setup wizard with API key validation
- Secure storage of configuration
- Detailed error messages for troubleshooting
Robust Error Handling
- Specific error messages for different API error conditions
- Consistent error format across all tools and prompts
- Transport-aware logging that doesn't interfere with the protocol
Development
License
MIT
Readwise MCP Server
A Model Context Protocol (MCP) server for accessing and interacting with your Readwise library.
Features
- Access highlights from your Readwise library
- Search for highlights using natural language queries
- Get books and documents from your library
- Seamless integration with Claude and other MCP-compatible assistants
- Enhanced prompt capabilities for highlight analysis
- Transport-aware logging system
- Robust error handling and validation
- MCP protocol compliance with proper request_id handling
- Health check endpoint for monitoring
- Improved setup wizard with API key validation
Project Structure
This repository is organized into the following key directories:
- src/: Main source code for the Readwise MCP server
- test-scripts/: Test scripts and utilities for validating MCP server functionality
- examples/: Example implementations and code samples
- dist/: Compiled JavaScript output (generated)
- scripts/: Utility scripts for development and testing
Installation
Setup
Before using the server, you need to configure your Readwise API key:
You can get your API key from https://readwise.io/access_token.
Usage
CLI
API
Testing with MCP Inspector
The project includes built-in support for testing with the MCP Inspector. You can use either the TypeScript script or the shell script to run the inspector.
Automated Tests
Run the automated test suite that verifies all tools and prompts:
The test suite verifies:
- Server startup and connection
- Tool availability and responses
- Prompt functionality
- Error handling
- Response format compliance
Each test provides detailed output and a summary of passed/failed cases.
Manual Testing
Using the Shell Script
Using the TypeScript Script
Available Options
-t, --transport <type>: Transport type (stdio or sse), default: stdio
-p, --port <number>: Port number for SSE transport, default: 3001
-d, --debug: Enable debug mode
Example Inspector Commands
Test a specific tool:
Test a prompt:
List available tools and prompts:
Testing Without a Readwise API Key
If you don't have a Readwise API key or don't want to use your real API key for testing, you can use the mock testing functionality:
This runs a test script that:
- Creates a mock implementation of the Readwise API
- Sets up the MCP server with this mock API
- Tests various endpoints with sample data
- Verifies server functionality without requiring a real API key
The mock implementation includes:
- Sample books, highlights, and documents
- Simulated network delays for realistic testing
- Error handling testing
Available Tools
- get_highlights: Get highlights from your Readwise library
- get_books: Get books from your Readwise library
- get_documents: Get documents from your Readwise library
- search_highlights: Search for highlights in your Readwise library
Available Prompts
- readwise_highlight: Process highlights from Readwise
- readwise_search: Search and process highlights from Readwise
Recent Improvements
Enhanced MCP Protocol Compliance
- Proper handling of request_id in all responses
- Validation of incoming requests against MCP protocol specifications
- Consistent error response format following MCP guidelines
Improved Setup Experience
- Interactive setup wizard with API key validation
- Secure storage of configuration
- Detailed error messages for troubleshooting
Robust Error Handling
- Specific error messages for different API error conditions
- Consistent error format across all tools and prompts
- Transport-aware logging that doesn't interfere with the protocol
Development
License
MIT