README.md•4 kB
# Calibre MCP Server
A lightweight Node.js MCP server for searching and reading books from your Calibre ebook library. Designed specifically for Windows compatibility.
## Features
- **Library Search**: Search your Calibre library by title, author, or content
- **Book Reading**: Retrieve and read book contents in various formats
- **Metadata Access**: Get detailed book information and metadata
- **Windows Compatible**: Optimized for Windows environments
- **Zero Dependencies**: Lightweight implementation with no external dependencies
## Prerequisites
- Node.js >= 16.0.0
- Calibre installed on Windows
## Installation
1. Clone this repository:
```bash
git clone https://github.com/yourusername/calibre-mcp-nodejs.git
cd calibre-mcp-nodejs
```
2. Install dependencies:
```bash
npm install
```
## Usage
### Starting the Server
```bash
npm start
```
### Available Tools
- `search`: Search for books in your Calibre library
- `fetch`: Retrieve specific content from books using epub:// URLs
### Example MCP Configuration
Add to your MCP client configuration:
```json
{
"mcpServers": {
"calibre": {
"command": "node",
"args": ["path/to/calibre-mcp-nodejs/server.js"]
}
}
}
```
## Configuration
The server automatically detects your Calibre library location. The search looks for Calibre in common installation paths:
- `C:\Program Files\Calibre2\`
- `C:\Program Files (x86)\Calibre2\`
- Custom paths via environment variables
## API Reference
### Search Books
```javascript
// Search by title
search({ query: "title:\"The Great Gatsby\"" })
// Search by author
search({ query: "author:\"F. Scott Fitzgerald\"" })
// Full-text search
search({ query: "green light" })
```
### Fetch Book Content
```javascript
// Fetch specific book content
fetch({ url: "epub://book_id/chapter_1" })
```
## Project Structure
```
calibre-mcp-nodejs/
├── server.js # Main MCP server
├── package.json # Dependencies and scripts
├── test.js # Test file
├── test.bat # Windows test script
└── README.md # This file
```
## Testing
Run the test:
```bash
npm test
```
Or use the Windows batch file:
```bash
test.bat
```
## Troubleshooting
### Common Issues
1. **Calibre Not Found**: Ensure Calibre is installed in a standard location
2. **Library Access**: Make sure the Calibre library is accessible and not locked
3. **Permissions**: Run with appropriate permissions to access Calibre files
### Debug Mode
Set the DEBUG environment variable for verbose logging:
```bash
set DEBUG=calibre:*
npm start
```
## Supported Formats
The server supports all formats that Calibre can handle:
- EPUB
- PDF
- MOBI
- AZW/AZW3
- TXT
- HTML
- And many more
## Performance
This lightweight server is designed for:
- Fast startup times
- Low memory usage
- Quick search responses
- Minimal system impact
## Comparison with RAG Version
This is the lightweight version. For advanced features like vector search, semantic similarity, and RAG capabilities, see [calibre-rag-mcp-nodejs](https://github.com/yourusername/calibre-rag-mcp-nodejs).
| Feature | Simple Version | RAG Version |
|---------|---------------|-------------|
| Basic Search | ✅ | ✅ |
| Book Reading | ✅ | ✅ |
| Dependencies | None | Many |
| Memory Usage | Low | High |
| Vector Search | ❌ | ✅ |
| Semantic Search | ❌ | ✅ |
| OCR Support | ❌ | ✅ |
| Project Organization | ❌ | ✅ |
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
## License
Licensed under the Apache License 2.0. See LICENSE file for details.
## Support
For issues and questions, please open an issue on GitHub.
## Changelog
### v2.0.0
- Improved Windows compatibility
- Enhanced search functionality
- Better error handling
- Optimized performance
### v1.0.0
- Initial release
- Basic search and fetch functionality
- Windows support