Content
# Readest MCP Server
A Model Context Protocol (MCP) server for Readest that enables AI assistants to access book content, reading progress, and notes from the Readest reading application.
## Features
- **Book Information**: Retrieve metadata about the currently open book (title, author, publisher, ISBN)
- **Table of Contents**: Access the complete book structure with hierarchical chapter organization
- **Reading Progress**: Track current reading position, chapter, and completion percentage
- **User Notes**: Retrieve all highlights, annotations, and comments made by the user
- **Chapter Content**: Get full chapter text with pagination support for large chapters
- **Aggregated Chapters**: Retrieve parent chapters with all their subsections combined
- **Full Context**: Get comprehensive book context in a single request
## Installation
### Prerequisites
- Node.js 18 or higher
- pnpm (recommended) or npm
- Readest desktop application
### Setup
1. Clone this repository:
```bash
git clone https://github.com/BlackStar1453/readest-mcp.git
cd readest-mcp
```
2. Install dependencies:
```bash
pnpm install
```
3. Build the server:
```bash
pnpm build
```
### Configure Claude Desktop
Add the MCP server to your Claude Desktop configuration file:
**macOS**: `~/.config/claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"readest": {
"command": "node",
"args": ["/absolute/path/to/readest-mcp/dist/index.js"]
}
}
}
```
## Usage
1. **Start Readest**: Launch the Readest desktop application
2. **Open a Book**: Open any EPUB book in Readest
3. **Use Claude Desktop**: The MCP tools will automatically be available in Claude
### Example Prompts
Ask Claude to:
- "What book am I currently reading?"
- "Show me the table of contents"
- "What's my current reading progress?"
- "Get my notes and highlights from this book"
- "Summarize the current chapter"
- "Find all mentions of [topic] in my book"
## Architecture
```
┌─────────────────────┐
│ Claude Desktop │
└──────────┬──────────┘
│ MCP Protocol
┌──────────▼──────────┐
│ MCP Server │
│ (Node.js) │
└──────────┬──────────┘
│ HTTP
┌──────────▼──────────┐
│ Readest Backend │
│ (Rust HTTP) │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Readest App │
│ (React/Tauri) │
└─────────────────────┘
```
## MCP Tools
### `get_current_book_info`
Returns metadata about the currently open book.
**Response includes:**
- Title, author, publisher
- ISBN, language
- Cover image URL
### `get_table_of_contents`
Returns the complete hierarchical table of contents.
**Response includes:**
- Chapter IDs and titles
- Nested structure with subitems
- Navigation links (href)
### `get_reading_progress`
Returns current reading position and statistics.
**Response includes:**
- Current chapter title
- Page number (current/total)
- Progress percentage
- Last update timestamp
### `get_book_notes`
Returns all user annotations and highlights.
**Response includes:**
- Highlight text and colors
- User notes and comments
- Chapter references
- Creation timestamps
### `get_current_chapter`
Returns the content of the currently reading chapter.
**Parameters:**
- `page` (optional): Page number for pagination (default: 1)
- `pageSize` (optional): Characters per page (default: 5000)
- `includeHtml` (optional): Include HTML with images (default: false)
### `get_aggregated_chapter`
Returns a parent chapter with all its subsections combined.
**Parameters:**
- `chapter_id` (required): ID of the parent chapter
### `get_full_context`
Returns all book information in a single request.
## Development
### Project Structure
```
readest-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── README.md # Documentation
└── scripts/ # Utility scripts
```
### Available Scripts
```bash
# Build for production
pnpm build
# Watch mode for development
pnpm watch
# Type checking
pnpm type-check
# Clean build artifacts
pnpm clean
```
### Testing
Test the MCP server manually:
```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
# Call a specific tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_current_book_info","arguments":{}}}' | node dist/index.js
```
### Debugging
1. Check if Readest HTTP server is running:
```bash
cat /tmp/readest-mcp-port.txt # Get the port
curl http://127.0.0.1:[PORT]/health
```
2. Enable debug logging:
```bash
DEBUG=readest:* node dist/index.js
```
3. Check Claude Desktop logs:
- macOS: `~/Library/Logs/Claude/`
- Windows: `%APPDATA%\Claude\logs\`
## Troubleshooting
### MCP server not connecting
1. **Verify Readest is running**: The desktop app must be open
2. **Check port file**: `/tmp/readest-mcp-port.txt` should exist
3. **Test HTTP endpoint**: `curl http://127.0.0.1:[PORT]/book-info`
4. **Restart Claude Desktop**: Sometimes required after config changes
### No book data returned
1. **Open a book**: Ensure a book is actually open in Readest
2. **Wait for sync**: Data sync may take a few seconds
3. **Check browser console**: Look for sync errors in Readest's DevTools
4. **Verify backend**: Check Rust backend logs for errors
### Chapter content issues
- Large chapters are automatically paginated
- Use `includeHtml: true` to get formatted content with images
- Aggregated chapters combine all subsections automatically
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is part of the Readest ecosystem. See the main [Readest repository](https://github.com/BlackStar1453/readest) for license details.
## Related Projects
- [Readest](https://github.com/BlackStar1453/readest) - Main reading application
- [MCP Specification](https://modelcontextprotocol.io) - Model Context Protocol docs
## Support
For issues or questions:
- Open an issue in this repository
- For Readest app issues, use the main Readest repository
- For MCP protocol questions, see the MCP documentation
## Acknowledgments
Built for the Readest reading application to enhance AI-assisted reading experiences.
