mcp-readwise

MCP server for Readwise built on FastMCP. Provides 17 tools covering highlights, books, tags, Reader documents, and bulk export.

Installation

uv sync

Or with pip:

pip install .

Configuration

Set the following environment variables:

Variable	Required	Default	Description
`READWISE_TOKEN`	Yes	-	Readwise API access token
`TRANSPORT`	No	`stdio`	Transport mode: `stdio` or `http`
`HOST`	No	`127.0.0.1`	HTTP server host
`PORT`	No	`8000`	HTTP server port
`MCP_API_KEY`	No	-	Bearer token for MCP Portal auth
`READWISE_BASE_URL`	No	`https://readwise.io`	Readwise API base URL

Get your Readwise access token at: https://readwise.io/access_token

Usage

Local (stdio)

READWISE_TOKEN=your_token uv run mcp-readwise

HTTP mode

READWISE_TOKEN=your_token TRANSPORT=http uv run mcp-readwise

Docker

cp .env.example .env  # Add your READWISE_TOKEN
docker compose up -d

Available Tools

Highlights

Tool	Description
`search_highlights`	Search using semantic, full-text, or hybrid mode
`list_highlights`	List with filters (book, tag, date) and pagination
`get_highlight`	Get by ID with book metadata
`create_highlight`	Create on a book with optional note/tags
`update_highlight`	Update text or note
`delete_highlight`	Delete by ID
`export_highlights`	Bulk export with cursor pagination

Books

Tool	Description
`list_books`	List with category/source/annotation filters
`get_book`	Get by ID

Reader

Tool	Description
`list_documents`	List Reader docs with location/category filters
`get_document`	Get by ID with full content
`save_url`	Save a URL to Reader
`update_progress`	Update reading progress (0.0-1.0)

Project Structure

mcp_readwise/
  server.py      # FastMCP app, tool registration, entry point
  config.py      # pydantic-settings configuration
  client.py      # Centralized httpx client (auth, retries, rate limits)
  auth.py        # Bearer token verifier for MCP Portal
  models/        # Pydantic response models
  tools/         # Tool functions by domain

Deployment

Deployed via Komodo to ubuntu-smurf-mirror, accessible through Cloudflare MCP Portal at mcp-readwise.cdit-dev.de.

License

MIT

Tool	Description
`list_tags`	List all tags
`create_tag`	Create a new tag
`delete_tag`	Delete by ID
`tag_highlight`	Add or remove a tag on a highlight

Readwise MCP HTTP Server