Provides specific configuration instructions for installing the MCP server on macOS, with details on Claude Desktop configuration file locations.
Allows saving YouTube content to Readwise Reader as a supported document category, enabling management and organization of YouTube videos alongside other reading materials.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Readwise Reader MCP Server save this article to my reading list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for the Readwise Reader API, built with TypeScript and the official Claude SDK.
Secure Authentication: Uses environment variables for token storage
Document Management: Save, list, update, and delete documents with complete metadata
Tag Management: List and filter by tags
Rich Filtering: Filter documents by location, category, tags, and more
Pagination Support: Handle large document collections
LLM-Friendly Content: HTML content automatically converted to clean text using r.jina.ai
Complete Data Access: Returns full document information including content, metadata, and timestamps
Related MCP server: Dynalist MCP Server
For detailed information about the Readwise Reader API endpoints, parameters, and examples, please refer to the official API documentation:
📖 Readwise Reader API Documentation
This MCP server implements all the core endpoints described in the official documentation.
npm install
npm run buildBuild the MCP server:
npm install
npm run buildGet your Readwise access token from: https://readwise.io/access_token
Add the server to your Claude Desktop configuration. Open your Claude Desktop settings and add this to your MCP servers configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"readwise-reader": {
"command": "node",
"args": ["/path/to/your/reader_readwise_mcp/dist/index.js"],
"env": {
"READWISE_TOKEN": "your_readwise_access_token_here"
}
}
}
}Replace:
/path/to/your/reader_readwise_mcp with the actual path to this project directory
your_readwise_access_token_here with your actual Readwise access token
Restart Claude Desktop
readwise_save_documentSave a document (URL or HTML content) to Readwise Reader.
Parameters:
url (required): URL of the document to save
html (optional): HTML content of the document
tags (optional): Array of tags to add
location (optional): Location to save (new, later, shortlist, archive, feed)
category (optional): Document category (article, book, tweet, pdf, email, youtube, podcast)
readwise_list_documentsList documents from Readwise Reader with optional filtering. Returns complete document information including metadata and LLM-friendly text content.
Parameters:
id (optional): Filter by specific document ID
updatedAfter (optional): Filter documents updated after this date (ISO 8601)
location (optional): Filter by document location
category (optional): Filter by document category
tag (optional): Filter by tag name
pageCursor (optional): Page cursor for pagination
withHtmlContent (optional): ⚠️ PERFORMANCE WARNING: Include HTML content in the response. This significantly slows down the API. Only use when explicitly requested by the user or when raw HTML is specifically needed for the task.
withFullContent (optional): ⚠️ PERFORMANCE WARNING: Include full converted text content in the response. This significantly slows down the API as it fetches and processes each document's content. Only use when explicitly requested by the user or when document content is specifically needed for analysis/reading. Default: false for performance.
Returns: Complete document objects with all available fields:
id, title, author, url, source_url, summary
published_date, image_url, location, category
tags, created_at, updated_at
content: LLM-friendly text content (converted from source_url or url via r.jina.ai)
readwise_update_documentUpdate a document in Readwise Reader.
Parameters:
id (required): Document ID to update
title (optional): New title
author (optional): New author
summary (optional): New summary
published_date (optional): New published date (ISO 8601)
image_url (optional): New image URL
location (optional): New location
category (optional): New category
readwise_delete_documentDelete a document from Readwise Reader.
Parameters:
id (required): Document ID to delete
readwise_list_tagsList all tags from Readwise Reader.
Parameters: None
readwise_topic_searchSearch documents in Readwise Reader by topic using regex matching on title, summary, notes, and tags.
Parameters:
searchTerms (required): Array of search terms to match against document content (case-insensitive regex matching)
Returns: Search results with matching documents including:
Search terms used
Total number of matches
Complete document objects with all available metadata (same fields as readwise_list_documents)
The server requires a Readwise access token to be provided via the READWISE_TOKEN environment variable. This token is used to authenticate all API requests to Readwise Reader.
Security Note: The token is stored in your MCP configuration and never exposed through Claude or the tools interface.
Default: 20 requests/minute
Document CREATE/UPDATE: 50 requests/minute
429 responses include "Retry-After" header
MIT
Delete a document from Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether this is permanent, reversible, requires specific permissions, or has rate limits. It provides minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple deletion operation and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after deletion (success confirmation, error handling), whether the action is permanent, or any authentication requirements. Given the complexity and lack of structured data, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'id' clearly documented in the schema as 'Document ID to delete'. The description doesn't add any additional meaning about the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a document from Readwise Reader'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'readwise_update_document' or 'readwise_save_document' in terms of when to choose deletion over other document operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'readwise_update_document' and 'readwise_save_document', there's no indication of when deletion is appropriate versus modification or creation, nor any mention of prerequisites or consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents from Readwise Reader with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Filter by specific document ID | |
| updatedAfter | No | Filter documents updated after this date (ISO 8601) | |
| addedAfter | No | Filter documents added after this date (ISO 8601). Note: This will fetch all documents first and then filter client-side. | |
| location | No | Filter by document location | |
| category | No | Filter by document category | |
| tag | No | Filter by tag name | |
| pageCursor | No | Page cursor for pagination | |
| withHtmlContent | No | ⚠️ PERFORMANCE WARNING: Include HTML content in the response. This significantly slows down the API. Only use when explicitly requested by the user or when raw HTML is specifically needed for the task. | |
| withFullContent | No | ⚠️ PERFORMANCE WARNING: Include full converted text content in the response. This significantly slows down the API as it fetches and processes each document's content. Only use when explicitly requested by the user or when document content is specifically needed for analysis/reading. Default: false for performance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'optional filtering' but fails to describe key behaviors such as pagination handling, rate limits, authentication requirements, or what the response format looks like. This is inadequate for a tool with 9 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core functionality without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the return format, pagination behavior, or error handling, which are critical for an agent to use this tool effectively. The schema handles parameters well, but overall context is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all parameters thoroughly. The description adds no additional meaning beyond 'optional filtering', which is implied by the schema. This meets the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('documents from Readwise Reader'), making the purpose understandable. However, it doesn't differentiate this tool from sibling tools like 'readwise_list_tags' or 'readwise_topic_search' beyond mentioning documents specifically, which is why it doesn't reach a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'readwise_topic_search' or 'readwise_save_document'. It mentions optional filtering but doesn't specify scenarios or exclusions, leaving the agent without context for tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags from Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, pagination, or what the return format looks like. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., tag list format), behavioral constraints, or how it fits with sibling tools. For a tool in this context, more information is needed to guide proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, earning a high baseline score. However, it doesn't add any semantic context beyond the schema, preventing a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all tags') and resource ('from Readwise Reader'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings like 'readwise_list_documents' or 'readwise_topic_search' beyond the resource type, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention use cases, prerequisites, or how it differs from sibling tools like 'readwise_list_documents' or 'readwise_topic_search', leaving the agent with no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a document (URL or HTML content) to Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL of the document to save | |
| html | No | HTML content of the document (optional) | |
| tags | No | Tags to add to the document | |
| location | No | Location to save the document (default: new) | |
| category | No | Category of the document (auto-detected if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool saves documents but doesn't mention authentication requirements, rate limits, error conditions, or what happens on success (e.g., whether it returns a document ID). For a write operation with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a tool with clear functionality and doesn't waste space on redundant information already available in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what happens after saving (success indicators, returned data), doesn't mention authentication or error handling, and provides minimal guidance despite rich parameter schema. The description should do more to compensate for the lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds minimal value beyond the schema by mentioning URL or HTML content, but doesn't provide additional context about parameter interactions (e.g., that html is optional and overrides url if both provided) or practical usage examples. Baseline 3 is appropriate when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Save') and resource ('a document to Readwise Reader'), specifying it accepts URL or HTML content. It distinguishes from siblings like delete_document and list_documents by focusing on creation rather than modification or retrieval. However, it doesn't explicitly differentiate from update_document which might also involve saving changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like update_document or list_documents. It mentions what the tool does but offers no context about prerequisites, typical use cases, or when other tools might be more appropriate given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search documents in Readwise Reader by topic using regex matching on title, summary, notes, and tags
| Name | Required | Description | Default |
|---|---|---|---|
| searchTerms | Yes | List of search terms to match against document content (case-insensitive regex matching) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions regex matching across multiple fields and case-insensitivity, which is useful. However, it doesn't describe important behavioral aspects like pagination, rate limits, authentication requirements, error handling, or what happens when no matches are found. For a search tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with all necessary information in a single sentence. Every word earns its place by specifying the action, target, method, and search fields without any redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search functionality with regex matching), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the search returns, how results are structured, whether there are limitations on search scope or result size, or how the regex matching actually works across the different fields. The description should provide more context for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the 'searchTerms' parameter with its type, constraints, and description. The description adds minimal value beyond the schema by mentioning the fields being searched (title, summary, notes, tags), but doesn't provide additional syntax, format, or usage details for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching documents in Readwise Reader by topic using regex matching across multiple fields (title, summary, notes, tags). It specifies the verb 'search' and resource 'documents' with scope 'by topic', but doesn't explicitly differentiate from sibling tools like 'readwise_list_documents' or 'readwise_save_document' beyond the search functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this search tool over 'readwise_list_documents' for listing all documents, or when to use it in conjunction with other tools. There's no context about prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a document in Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID to update | |
| title | No | New title for the document | |
| author | No | New author for the document | |
| summary | No | New summary for the document | |
| published_date | No | New published date (ISO 8601) | |
| image_url | No | New image URL for the document | |
| location | No | New location for the document | |
| category | No | New category for the document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Update' implies mutation, it doesn't specify permission requirements, whether changes are reversible, rate limits, or what happens to fields not mentioned. This leaves significant gaps for a mutation tool with 8 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 8 parameters and no annotations or output schema, the description is inadequate. It doesn't address behavioral aspects like permissions, side effects, or response format, leaving the agent with insufficient context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly with descriptions and enums. The description adds no additional parameter information beyond what's in the schema, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('a document in Readwise Reader'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'readwise_save_document' which might have overlapping functionality, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when-not-to-use scenarios, or how it differs from sibling tools like 'readwise_save_document' or 'readwise_delete_document'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: list_documents, save_document, update_document, delete_document, list_tags, and topic_search. There is no overlap in functionality, and the descriptions clearly differentiate the operations on documents versus tags versus search.
All tools follow a consistent 'readwise_verb_noun' pattern with snake_case throughout. The verbs (list, save, update, delete, search) are standard and predictable, making the tool set easy to navigate and understand.
With 6 tools, this server is well-scoped for managing documents in Readwise Reader. It covers core CRUD operations (create/save, read/list, update, delete) plus additional utilities (list_tags, topic_search), which is appropriate for the domain without being overwhelming or insufficient.
The tool set provides complete CRUD coverage for documents (save, list, update, delete) and includes essential extras like tag management and topic-based search. There are no obvious gaps for typical document management workflows in Readwise Reader.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search, read, create and edit your Memol notes from Claude. Team note-taking with AI search.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Run UX research from Claude — create card sort studies, list studies, pull headline stats.
Search, read, and write highlights, notes, screenshots, collections, projects, and tags in Gleanit.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/edricgsh/Readwise-Reader-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
