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.

Before beginning the MCP setup, make sure you have Node installed. The Readwise MCP relies on Node to perform the connection, so it won't work if Node is missing.

  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.
Click 'Edit Config' in the Claude desktop app.
  1. 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!)
  2. Add the following entry to your claude_desktop_config.json file.

IMPORTANT: Replace the ACCESS_TOKEN value with your Readwise Access Token!

{
  "mcpServers": {
    "Readwise MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@readwise/readwise-mcp"
      ],
      "env": {
        "ACCESS_TOKEN": "XXXXXXXXX"
      }
    }
  }
}
  1. Start chatting with your highlights in Claude!
Search your Readwise highlights from 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.

An example of a config file with pre-existing content.

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.

Icons indicating that an MCP server is configured.

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.

Modal that indicates the Readwise MCP server is connected.

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 (➋).

Select your OS and download the Node installer.

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.

Search for the Install Server command in Raycast.

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.
  • 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."
Set up the Readwise MCP inside Raycast.

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).

Search your Readwise highlights with Raycast AI Chat.

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.

Give Raycast permission to run a Readwise MCP search.

If you want to learn more about how MCP servers work with Raycast, check out the MCP page of the Raycast Manual.

Use the Readwise MCP with ChatGPT

At this time, only ChatGPT users with Pro, Team, or Enterprise plans have access to the MCP functionality of ChatGPT. This feature is not currently available for users with free or Plus accounts.

To get started with the Readwise MCP in ChatGPT, go to chatgpt.com and log in to your account. Open Settings from the bottom left corner of the screen.

Open ChatGPT's Settings menu.

Go to the Connectors option in the Settings menu sidebar, then click the Create button.

Click the Create button in the Connectors menu.

Fill out the form with the following information:

  • Logo: (optional) Upload an image to represent the connection. We've made one with the Readwise logo that you can download here, to make the connection look properly official.

Download Readwise icon

  • Name: This can be whatever you'd like to use to find the connection in the list. We recommend "Readwise" or "Readwise MCP" to keep things simple.
  • Description: (optional) You can leave this blank, or you can enter something like "Search your Readwise highlights."
  • MCP Server URL: https://mcp.readwise.io/sse
  • Authentication: Use the OAuth option.
  • I trust this application: Check this box. (We promise we won't steal your data!)

Once you click Create, you'll be briefly redirected to the Readwise website to authenticate the connection. Click Authorize to continue.

Authorize ChatGPT to access your highlights.

After authorizing, you may initially see an error about search action not found. If you do, click the Refresh button and the error message should disappear.

Click Refresh to resolve the error.

Back in the chat interfact, turn on the Connected apps option in the + menu, then select Readwise from your Sources list.

Turn on the Readwise source in ChatGPT's connections.

Once you've selected Readwise as a Source, you can chat with your Readwise highlights directly in ChatGPT.

Chat with your Readwise highlights in ChatGPT.
Previous
Chat With Highlights

Have a suggestion?

We're pretty familiar with our product, so we occasionally fall victim to the Curse of Knowledge. If any part of this documentation confuses you or seems incomplete, please let us know!