Readwise

🚀 Readwise MCP Server

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

🚀 Quick Start

The Readwise MCP Server is a powerful tool that allows you to access and interact with your Readwise library through the MCP protocol. It provides various functions to help you process and analyze information.

✨ Features

• Get Highlights: Retrieve highlighted content from your Readwise library.
• Search Highlights: Search for highlighted content in your Readwise library.
• Get Books: Obtain book information from your Readwise library.
• Get Documents: Fetch document information from your Readwise library.

📦 Installation

You can install the project using the following commands:

Method 1: Install from npm

npm install readwise-mcp-server

Method 2: Clone the repository and install dependencies

1. Clone the repository:

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. Install dependencies:

   npm install
   

💻 Usage Examples

Command Line Interface (CLI)

• Start the server (default mode):

  npm start
  

• Start the server (development mode):

  npm run dev
  

• Specify the API key:

  npm start -- --apiKey your_api_key_here
  

• Enable debug mode:

  npm start -- --debug
  

Programmer Interface (API)

const { MCPServer } = require('readwise-mcp-server');

// Create a server instance
const server = new MCPServer({
  apiKey: 'your_api_key_here'
});

// Start the server
server.start();

📚 Documentation

Project Structure

The project is divided into the following main parts:

• src: The main codebase, containing the core implementation of the server.
• test-scripts: Test scripts for automated testing and function verification.
• examples: Sample code demonstrating how to use the MCP server.
• dist: The build output directory, containing compiled files.
• scripts: Startup scripts and other development tools.

Configuration

Method 1: Run the setup wizard

npm run setup

Method 2: Use the API key directly

1. Ensure you have a valid Readwise API key.
2. Start the server:

   npm start -- --apiKey your_api_key_here
   

Testing

Automated testing

Run the following command to execute all tests:

npm test

Testing with the MCP inspector

1. Install the inspection tool:

   npm install mcp-inspector
   

2. Start the server and connect using the inspection tool.

Testing without an API key

If you don't have an API key or don't want to use a real key for testing, you can run the following command:

npm run test-mock

Available Tools

• get_highlights: Retrieve highlighted content from your Readwise library.
• get_books: Obtain book information from your Readwise library.
• get_documents: Fetch document information from your Readwise library.
• search_highlights: Search for highlighted content in your Readwise library.

Available Prompts

• readwise_highlight: Process Readwise highlighted content.
  • Supports summarization, analysis, association recognition, and question generation.
  • Includes powerful error handling and parameter validation.
  • Provides user-friendly formatted output.
• readwise_search: Search for and process highlighted content in Readwise.
  • Provides formatted search results, including source information.
  • Smoothly handles API errors.
  • Includes validation of required parameters.

Recent Improvements

Enhanced MCP protocol compliance

• Correctly handle the request_id in all responses.
• Validate inbound requests to comply with MCP protocol specifications.
• Maintain a consistent and standard error response format.

Improved developer experience

• Improved the output of debugging information.
• Simplified the configuration process.
• Added detailed documentation and examples.

Development

Local development

1. Clone the repository:

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm run dev
   

Contribution guidelines

• Please refer to the contribution guidelines in the project repository.

📄 License

This project is licensed under the MIT License.