Readwise MCP

🚀 Readwise MCP Server

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

✨ Features

• Access your highlighted content in Readwise.
• Search for highlighted content using natural language queries.
• Retrieve information about your books in Readwise.
• Obtain your document materials in Readwise.
• Search and process highlighted content from Readwise, supporting summarization, analysis, related searches, and question generation.

📁 Project Structure

# Main code directory
src/

# Test script directory
test-scripts/

# Documentation directory
docs/

# Example configuration file directory
examples/

📦 Installation

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

⚙️ Configuration

1. Run the setup wizard

   npm run setup
   

2. Configure the API key
   • Open the config.js file.
   • Add your Readwise API key to it.
   • Save the file.

💻 Usage Examples

CLI Usage

# Get highlighted content
npm run get-highlights -- [--page=1 --limit=10]

# Search for highlighted content
npm run search-highlights -- [--query="your search term" --exact]

API Usage

const { MCPClient } = require('@readwise/mcp-client');

// Initialize the client
const client = new MCPClient('your-api-key');

// Get highlighted content
async function getHighlights() {
    try {
        const response = await client.getHighlights({
            page: 1,
            limit: 10
        });
        console.log(response.data);
    } catch (error) {
        console.error('Failed to get highlights:', error.message);
    }
}

// Search for highlighted content
async function searchHighlights() {
    try {
        const response = await client.searchHighlights({
            query: 'your search term',
            exact: true
        });
        console.log(response.data);
    } catch (error) {
        console.error('Failed to search for highlights:', error.message);
    }
}

🧪 Testing

1. Run automated tests

   npm test
   

2. Use manual testing tools
   • Use the get_highlights tool to get highlighted content.
   • Use the search_highlights tool to search for highlighted content.
3. Use the Mock test environment

   npm run test-mock
   

🛠️ Available Tools

• get_highlights: Retrieve highlighted content from your Readwise library.
• get_books: Get information about your books in Readwise.
• get_documents: Obtain your document materials in Readwise.
• search_highlights: Search for highlighted content in your Readwise library.

💡 Available Prompts

• readwise_highlight: Process highlighted content from Readwise.
  • Supports summarization, analysis, related searches, and question generation.
  • Has powerful error handling and parameter validation.
  • Provides reader - friendly formatted highlighted content.
• readwise_search: Search and process highlighted content from Readwise.
  • Provides formatted search results, including source information.
  • Handles API errors smoothly and provides user - friendly messages.
  • Includes validation of required parameters.

🌟 Recent Improvements

Enhanced MCP Protocol Compatibility

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

Improved Setup Experience

• Provide an interactive setup wizard.
• Securely store configuration information.
• Provide detailed error messages for troubleshooting.

Robust Error Handling Mechanism

• Provide specific error messages for different API error situations.
• Maintain a consistent error format across all tools and prompts.
• Implement transport - aware logging without interfering with the protocol flow.

🛠️ Development Information

# Build the project
npm run build

# Execute tests
npm test

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

# Code linting
npm run lint

📄 License

MIT