readwise-mcp

A Model Context Protocol (MCP) server for accessing and interacting with your Readwise library.

• 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

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
  • smart-mcp-test.sh: Main testing script for both stdio and SSE transports
  • run-simple-server.sh: Script to run a simple MCP server
  • See test-scripts/README.md for complete documentation
• examples/: Example implementations and code samples
  • examples/mcp-implementations/: Basic MCP server implementations
  • examples/test-clients/: Client-side test scripts
  • See examples/README.md for complete documentation
• dist/: Compiled JavaScript output (generated)
• scripts/: Utility scripts for development and testing

# Install from npm
npm install -g readwise-mcp

# Or clone the repository and install dependencies
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build

Before using the server, you need to configure your Readwise API key:

# Run the setup wizard
npm run setup

# Or start with the API key directly
readwise-mcp --api-key YOUR_API_KEY

You can get your API key from https://readwise.io/access_token.

# Start with stdio transport (default, for Claude Desktop)
readwise-mcp

# Start with SSE transport (for web-based integrations)
readwise-mcp --transport sse --port 3000

# Enable debug logging
readwise-mcp --debug

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY',
  3000, // port
  logger,
  'sse' // transport
);

await server.start();

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.

Run the automated test suite that verifies all tools and prompts:

# Run automated inspector tests
npm run test-inspector

# Run in CI mode (exits with status code)
npm run test-inspector:ci

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.

# Test with stdio transport (default)
./scripts/inspector.sh

# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001

# Enable debug mode
./scripts/inspector.sh -d

# Full options
./scripts/inspector.sh --transport sse --port 3001 --debug

# Test with stdio transport (default)
npm run inspector

# Test with SSE transport
npm run inspector -- -t sse -p 3001

# Enable debug mode
npm run inspector -- -d

# Full options
npm run inspector -- --transport sse --port 3001 --debug

• -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

Test a specific tool:

./scripts/inspector.sh
> tool get-highlights --parameters '{"page": 1, "page_size": 10}'

Test a prompt:

./scripts/inspector.sh
> prompt search-highlights --parameters '{"query": "python"}'

List available tools and prompts:

./scripts/inspector.sh
> list tools
> list prompts

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:

npm run test-mock

This runs a test script that:

1. Creates a mock implementation of the Readwise API
2. Sets up the MCP server with this mock API
3. Tests various endpoints with sample data
4. 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

• 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

• readwise_highlight: Process highlights from Readwise

  • Supports summarization, analysis, connection finding, and question generation
  • Includes robust error handling and parameter validation
  • Formats highlights in a reader-friendly way

• readwise_search: Search and process highlights from Readwise

  • Provides formatted search results with source information
  • Handles API errors gracefully with user-friendly messages
  • Includes validation for required parameters

• Proper handling of request_id in all responses
• Validation of incoming requests against MCP protocol specifications
• Consistent error response format following MCP guidelines

• Interactive setup wizard with API key validation
• Secure storage of configuration
• Detailed error messages for troubleshooting

• 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

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev:watch

# Lint code
npm run lint

MIT