Readwise

You can run a lightweight Python MCP server to sync and manage Readwise highlights and documents with token-efficient, single-file execution. It preserves existing state, optimizes API calls, and exposes a focused set of tools for daily import, backfill, and lookup tasks.

How to use

You will run the Readwise MCP Server locally and connect to it from your MCP client. The server exposes a set of actions that let you fetch today’s highlights, import recent items, backfill by date, retrieve book highlights, search highlights, inspect current import state, initialize ranges from on-disk documents, and reset state when needed. Each action returns a structured summary with status and metrics so you can programmatically respond to successes or skips.

Use the MCP client to call actions by name, supply parameters when required, and handle the returned status and counts. You don’t need raw protocol details here—focus on the high-level operations your workflow requires, such as importing recent items, backfilling a date range, or checking the current state.

How to install

Prerequisites: Python 3 and a POSIX shell. You will set up a virtual environment, install dependencies, and configure environment variables for token access and vault path.

# 1. Clone the project repository
git clone https://github.com/ngpestelos/readwise-mcp-server.git
cd readwise-mcp-server

# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

Configure environment and MCP entry

Create or update your MCP configuration to run the server as a local process. The command uses your Python virtual environment and points to the server script. You must also provide the required environment variables.

{
  "mcpServers": {
    "readwise": {
      "command": "/absolute/path/to/readwise-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/readwise-mcp-server/server.py"],
      "env": {
        "READWISE_TOKEN": "your_token_here",
        "VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

What you’ll see when you call the server

The Readwise MCP Server returns structured summaries for each action. For example, importing recently discovered items will indicate how many were imported, skipped, and the total analyzed. Backfilling reports include pages processed and whether the target date was reached.

Tools and actions exposed

Readwise MCP Server provides eight core actions. You will call these by name from your MCP client and handle the returned status and counts.

State and files you’ll interact with

The server maintains a state file that tracks the last import timestamp, oldest imported date, and synced ranges. It also records whether a backfill is in progress. You can rebuild ranges from the filesystem if needed.

Typical workflow example

Set up the server, then perform a daily import to bring in new highlights, followed by a backfill if you need to cover a date window. Periodically inspect the state to ensure ranges are up to date, and initialize ranges if you’ve added new documents to disk.

Security and maintenance notes

Store your Readwise token securely and limit vault access. Regularly update dependencies in a controlled environment and monitor logs for any unusual activity.

Testing locally

Activate the virtual environment and run your server script. Use your MCP client to exercise each action and verify you receive the expected status and counts.

Available tools

readwise_daily_review

Fetch today's highlights and save to the Daily Reviews directory, returning status, count, and the file path.

readwise_import_recent

Import recent documents since the last import with automatic deduplication, returning counts of imported, skipped, and total analyzed.

readwise_backfill

Paginate backwards to a target date with synced range optimization, returning import stats, page count, and whether the target was reached.

readwise_book_highlights

Retrieve highlights for a specific book by title or ID, returning count and the highlights.

readwise_search_highlights

Search highlights by textual query with an adjustable limit, returning matches and total count.

readwise_state_info

Show current import state and synced ranges with metadata like last import and disk counts.

readwise_init_ranges

Scan the filesystem to build synced ranges from existing documents and report analyzed document count.

readwise_reset_state

Reset the import state, with an option to preserve synced ranges, and report the result.