How to use the Readwise MCP

What is the Readwise MCP?

The Model Context Protocol (MCP) standardizes how applications provide context to Large Language Models (LLMs). The Readwise MCP was created to act as a bridge between LLM clients and Readwise.

In simpler terms, setting up your own Readwise MCP server allows you to chat with your Readwise highlights using an external chat client (such as Claude), rather than the Chat function on the Readwise website.

Use the Readwise MCP with Claude Desktop

The following instructions will help you configure the Readwise MCP to work inside of your Claude Desktop app.

1. Open the Claude Desktop app. If you don't have the desktop version install yet, you can download it here.
2. In the sidebar of the app, navigate to File > Settings > Developer (cmd + , on Mac).
3. Click Edit Config. This will take you to the configuration file's location in your file browser.

4. Open the config file in your text editor of choice. (Visual Studio Code is a great free option if you don't have one already!)
5. Add the following entry to your claude_desktop_config.json file.

{
  "mcpServers": {
    "Readwise MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@readwise/readwise-mcp"
      ],
      "env": {
        "ACCESS_TOKEN": "XXXXXXXXX"
      }
    }
  }
}

6. Start chatting with your highlights in Claude!

FAQs and troubleshooting

I'm getting an error when I add the mcpServers entry to my config file. What do I do?

If your claude_desktop_config.json file is empty when you open it, you can simply copy/paste the code provided in the instructions above.

However, if your file already has any content, you'll need to make sure you only add the actual mcpServers entry, without the exterior curly brackets. The screenshot below shows an example of how the new entry should be added in a file that already has an updated setting for Claude's global activation hotkey.

Note the comma added after the existing globalShortcut: "Ctrl+Space" code!

How can I tell that the MCP server is set up?

Once you've set up your MCP config, the New Chat screen of Claude will display a couple of new icons.

The first icon indicates the number of MCP tools you've set up to work with Claude. If Readwise is your first, it should say 1. The second icon indicates that an MCP server is connected and able to share context with Claude.

Clicking either icon will open a modal and display information about the Readwise connection.

How do I install Node?

If you do any programming in your daily life, either for work or as a hobby, there's a good chance you already have Node installed on your computer. But if you've never needed it before (and most people likely haven't!), you can download it from the NodeJS website.

The simplest installation option is usually the installer, which you can download by selecting your operating system (➊) and then clicking the green button (➋).

You shouldn't need to do anything other than install it. The Readwise MCP configuration just needs to be able to find it on your system!

Why did I get an error while chatting?

When using this server, you may occasionally encounter MCP errors during your conversations with Claude. If you experience an error, we recommend switching between different Claude models (e.g. from Claude 3.5 Haiku to Claude 3.7 Sonnet), which will often resolve the issue.

Use the Readwise MCP with Raycast

Raycast is a supercharged launcher and productivity tool for MacOS. Among its many other capabilites, Raycast now has the ability to hook into MCP servers while using its AI Chat feature.

To get started with the Readwise MCP in Raycast, search for the Install Server command of the Raycast MCP extension.

Fill out the install form with the following information:

• Icon: Select an icon from the Raycast options. (The "Blockquote" option is decently apt!)
• Name: This can be whatever you'd like to use to reference the server in your AI chats. We recommend "Readwise" or "Readwise MCP" to keep things simple.
• Command: npx
• Arguments: -y @readwise/readwise-mcp
• Environment: This is a two part field. Click "Add Item" to reveal the subfields.
  • Key: ACCESS_TOKEN
  • Value: Your Readwise Access Token.
• Description: (optional) You can probably leave this blank if you're just using the server for your own purposes, or you can enter something like "Search your Readwise highlights."

Once you configure the server, you can use it in the Raycast AI Chat (quickly accessible by opening Raycast and pressing tab) by typing @ and whatever you used in the Name field (e.g. @readwise-mcp).

Note that it might ask you to confirm that you want to run the command before it actually executes. You can quickly authorize it with cmd + enter to continue with the chat.