Skip to main content

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 .zip files (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

  1. Create src/annotation_extractor/backends/yourreader.py implementing EReaderBackend
  2. Add your backend to _ALL_BACKENDS in registry.py
  3. No changes needed to server.py or models.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)

Source distribution for annotation-extractor 0.4.1
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)

Table of built distributions (wheels) for annotation-extractor 0.4.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page