readwise-mcp

An MCP server that exposes Readwise and Reader operations as tools for AI agents — Claude Code, Claude Desktop, or any MCP client.

Built on readwise-plus. This server is a thin, agent-friendly layer over readwise-plus, a comprehensive async Python SDK for the Readwise (v2) and Reader (v3) APIs. readwise-plus does the real work — auth, pagination, typed models, retries — and readwise-mcp maps it to MCP tools. If you want to script Readwise directly in Python, use readwise-plus; if you want an agent to do it for you, use this.

It gives an agent nine tools for saving, searching, reading, and organizing your Reader documents and Readwise highlights — so you can ask it to "find that article I archived last week" or "save this URL to my reading list" and have it actually do it.

Requirements

• Python 3.12+

• A Readwise access token — get one at https://readwise.io/access_token

• uv (recommended) for the zero-install uvx launch path

Related MCP server: Reader MCP Server

Authentication

The server reads READWISE_API_KEY from the environment, falling back to a READWISE_API_KEY= line in ~/.env. Provide it either way — via the MCP client config (below), an exported shell variable, or ~/.env. See .env.example.

Install & register

Claude Code

claude mcp add readwise --env READWISE_API_KEY=your-token -- uvx readwise-mcp

(Omit --env ... if you already keep READWISE_API_KEY in ~/.env.)

Any MCP client (Claude Desktop, etc.)

Add this to the client's MCP server config (e.g. claude_desktop_config.json or ~/.claude.json):

{
  "mcpServers": {
    "readwise": {
      "command": "uvx",
      "args": ["readwise-mcp"],
      "env": { "READWISE_API_KEY": "your-token" }
    }
  }
}

uvx readwise-mcp fetches and runs the latest published version on demand — no manual install step. Prefer a pinned install? Use uv tool install readwise-mcp and point command at readwise-mcp.

From source

git clone https://github.com/EvanOman/readwise-mcp
cd readwise-mcp
uv sync --dev

Then register the local checkout:

{
  "mcpServers": {
    "readwise": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/readwise-mcp", "python", "-m", "readwise_mcp"],
      "env": { "READWISE_API_KEY": "your-token" }
    }
  }
}

Verify it connected: claude mcp list should show readwise: ... Connected.

How to use

Once the server is registered, you don't call the tools directly — you talk to your agent in plain language and it picks the right tool. Some things you can ask:

Walkthrough: "find and read that article"

You: Find the article I saved about the OpenAI harness engineering post and give me the key points.

Behind the scenes the agent:

1. Calls search_documents(query="harness engineering") — a title substring search across your library — and gets back compact summaries (id, title, author, location), no body text.

2. Picks the best match and calls get_document(document_id=...) to pull the full HTML content.

3. Reads the content and answers you.

Notes on behavior

• Search is title-substring, client-side. query filters on the document title, not full text. To narrow the set first, combine it with location (new/later/archive), category, or tags.

• get_document is the only call that returns full content. search_documents deliberately returns summaries so the agent can scan cheaply, then fetch the one it wants.

• Uploads: save_to_reader can save a plain URL, or upload your own HTML by passing html= alongside a synthetic url (used as the unique id).

• Errors are data, not exceptions. Tools return {"error": "..."} so the agent can read the problem and recover rather than crashing.

• Deletes are permanent. delete_document cannot be undone.

• Documents saved through this server are tagged saved_using="readwise-mcp" in Reader.

Tools

Documents (Reader v3)

Highlights (Readwise v2)

Books (Readwise v2)

Design

Tools are shaped for agent ergonomics: a small set of well-composed tools rather than a thin wrapper per endpoint. Results are returned as compact JSON strings, and errors come back as {"error": ...} payloads instead of exceptions, so an agent can read and react to them. All Readwise access goes through the readwise-plus SDK's async client.

Development

just fc         # format, lint-fix, lint, type-check, test (run before every commit)
just test       # unit tests (mocked HTTP, no network)
just test-live  # live tests against the real Readwise API (requires READWISE_API_KEY)
just ci         # what CI runs: lint, format-check, type, test

Stack: uv · ruff · ty · pytest · just.

Releases are automated with release-please: merging the release PR tags a version and publishes to PyPI via trusted publishing.

License

MIT — see LICENSE. Built on readwise-plus, also MIT.