reader

This MCP server exposes your Readwise Reader library to MCP-compatible clients (such as Claude Desktop or VS Code) via the MCP protocol. The primary tool available in this server is list_documents, which lets MCP clients fetch documents from Readwise Reader with optional filters like location (new, later, shortlist, archive, feed), updatedAfter timestamps, and an option to include HTML content in the results. The server acts as a bridge between MCP clients and your Reader repository, enabling seamless querying, listing, and retrieval of documents and their metadata. To use it with a client, point the client’s MCP configuration to this local uv server and supply the required ACCESS_TOKEN for Readwise Reader access.

You can connect via Claude Desktop, VS Code, or any MCP-compliant client by configuring the mcpServers section in your client settings. For local usage, start uv with the directory pointing to this server's project path and run main.py, ensuring ACCESS_TOKEN is set (either as an environment variable or in an .env file in the project directory). The client will then be able to issue MCP requests such as listing documents, retrieving document content, or updating metadata through the reader MCP server.

Prerequisites:

• Python 3.8+ installed on your system
• Access token for Readwise Reader API (or an .env file in the project directory containing ACCESS_TOKEN)
• urllib/HTTP client access from your MCP client

Installation steps:

1. Obtain the Reader MCP server repository (download or clone).
2. Ensure Python is installed and available in your PATH.
3. Install the uv tool (uvx) so you can run the MCP server locally:
   • Option A (recommended): install via pipx
     • python3 -m pip install --user pipx
     • ~/.local/bin/pipx install uvx
     • Ensure the uv executable is in your PATH
   • Option B: install uvx via pip (less common):
     • python3 -m pip install uvx
     • Ensure the uv command is available in your PATH
4. Prepare environment variables:
   • Create an .env file in the project directory or export ACCESS_TOKEN=your_readwise_access_token
5. Run the server:
   • uv --directory /absolute/path/to/your/reader/server run main.py
   • Alternatively, use your editor/CLI to start with the provided command from the README’s example, ensuring the directory path points to this server’s location.

Note: The exact command may vary slightly depending on how you installed uvx. The key is that the server is started from the project directory containing main.py and that ACCESS_TOKEN (Readwise Reader API token) is supplied either via env or an .env file.

Tips and common issues:

• Ensure the path provided in --directory is absolute and points to the root of this MCP server project.
• The ACCESS_TOKEN must be valid for Readwise Reader; without it, document listing and retrieval may fail.
• If your MCP client requires a different client configuration format, adapt the mcpServers entry accordingly but keep the same command (uv) and directory structure.
• If you encounter connection issues, verify that the uv process is running and that the port/communication channel used by your MCP client matches your environment (some setups may require explicit port exposure in a custom uv command).
• You can store ACCESS_TOKEN in an .env file in the project root to simplify local startup; the server should load environment variables from that file if configured.
• This server supports listing documents with pagination via pageCursor; use updatedAfter to filter by modification times when needed.