annotation-extractor
MCP server for extracting annotations, highlights, and reading progress from e-readers.
Supports Kobo, Kindle, and Boox.
Install
pip install annotation-extractor
As an Agent Skill
Install as a reusable skill for any AI coding agent via skills.sh:
npx skills add rkaushik29/annotation-extractor-mcp
Or from source:
git clone https://github.com/rkaushik29/annotation-extractor-mcp.git
cd annotation-extractor
pip install -e .
Usage
Connect your e-reader via USB, add the MCP server to your agent, and start asking questions about your reading.
| Client | Setup |
|---|---|
| Claude Code | claude mcp add annotations -- annotation-extractor |
| Claude Desktop | Add to claude_desktop_config.json: {"mcpServers": {"annotations": {"command": "annotation-extractor"}}} |
| OpenClaw | openclaw mcp add annotations -- annotation-extractor |
| Gemini CLI | Add to ~/.gemini/settings.json: {"mcpServers": {"annotations": {"command": "annotation-extractor"}}} |
| Codex | codex --mcp-config mcp.json with mcp.json: {"mcpServers": {"annotations": {"command": "annotation-extractor"}}} |
Try it out
Once the MCP is connected and your e-reader is plugged in, try asking your agent:
"What are my highlights from the last book I read?"
"Search my annotations for anything about consciousness"
"Show me all the notes I took while reading Neuromancer"
Environment variables
If auto-detection doesn't find your device, you can point to the data source directly:
KOBO_DB_PATH=/path/to/KoboReader.sqlite annotation-extractor
KINDLE_CLIPPINGS_PATH=/path/to/My\ Clippings.txt annotation-extractor
BOOX_EXPORT_PATH=/path/to/boox-export annotation-extractor
For handwritten note extraction and rendering, these optional variables are also supported:
KINDLE_SCRIBE_PATH=/path/to/kindle-mount annotation-extractor
KINDLE_SCRIBE_CONVERTER=calibre-debug annotation-extractor
BOOX_NOTE_RENDERER=onyx_render.py annotation-extractor
Supported e-readers
| Reader | Data source |
|---|---|
| Kobo | .kobo/KoboReader.sqlite via USB |
| Kindle | My Clippings.txt via USB |
| Boox | Annotation export directory (one .txt file per book) via USB |
Handwritten notes are supported for:
- Kindle Scribe notebooks via
.notebooks/(raw export, optional render via KFX Input) - Boox handwritten exports (
.pdf/.png) and local backup.zipfiles (optional render)
Tools
| Tool | Description |
|---|---|
list_books |
List all books, optionally filtered to those with annotations |
get_annotations |
Get highlights and notes for a specific book (by title or ID) |
search_annotations |
Full-text search across all highlights and notes |
get_reading_progress |
Reading progress, time spent, and status for all books |
get_book_details |
Detailed metadata for a specific book |
get_handwritten_notes |
List handwritten note artifacts (Kindle Scribe / Boox) |
export_handwritten_notes |
Export handwritten note artifacts to a local directory |
All tools accept optional backend_name (e.g., "kobo", "kindle", "boox") and db_path parameters. When omitted, the server auto-detects connected devices.
Adding a new backend
- Create
src/annotation_extractor/backends/yourreader.pyimplementingEReaderBackend - Add your backend to
_ALL_BACKENDSinregistry.py - No changes needed to
server.pyormodels.py
Development
git clone https://github.com/rohitkaushik/annotation-extractor.git
cd annotation-extractor
pip install -e ".[dev]"
pytest
License
MIT
Metadata
Release files for annotation-extractor 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| annotation_extractor-0.4.1.tar.gz | 24.9 kB | With provenance | Details for annotation_extractor-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annotation_extractor-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for annotation_extractor-0.4.1-py3-none-any.whl |
Total release size: 47.4 kB
Release files / annotation_extractor-0.4.1.tar.gz
| Download URL | annotation_extractor-0.4.1.tar.gz |
|---|---|
| Size | 24.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
98cc45a0786d72fab879f1d98b6cbb787355c71e2c904c46479e2db265eb5958
|
|
BLAKE2b-256 checksum How to use checksums |
acf81d50b5a8e618eeb17a49cd554e83d898fc3ba0e7384133c7c4a06734f933
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logRelease files / annotation_extractor-0.4.1-py3-none-any.whl
| Download URL | annotation_extractor-0.4.1-py3-none-any.whl |
|---|---|
| Size | 22.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c537180ec5e7751309e137b33147fe7f15e26484c39c92221e74b5c68e4f1c3d
|
|
BLAKE2b-256 checksum How to use checksums |
286a4a759af2f9b9572061679e31c1d2f0903351632b2c17159956fcf69ce15c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logSecurity for annotation-extractor 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for annotation_extractor-0.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.