Skip to main content
Glama
Sign In
enesjakozh
Reader MCP Server

Reader MCP Server

by xinthink
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Reader MCP Server

Overview

A Model Context Protocol (MCP) server that seamlessly integrates with your Readwise Reader library. This server enables MCP-compatible clients like Claude and VS Code to interact with your Reader library, providing capabilities for document listing, retrieval, and updates. It serves as a bridge between MCP clients and your personal knowledge repository in Readwise Reader.

Related MCP server: @lex-tools/codebase-context-dumper

Components

Tools

  • list_documents

    • List documents from Reader with flexible filtering and pagination.

    • Input:

      • location (string, optional): Folder to filter by. One of new, later, shortlist, archive, feed.

      • updatedAfter (string, optional): Only return documents updated after this ISO8601 timestamp.

      • withContent (boolean, optional): If true, include HTML content in results (default: false).

      • pageCursor (string, optional): Pagination cursor for fetching the next page.

    • Returns:

      • JSON object with a list of documents, each including metadata and (optionally) content, plus pagination info.

Usage with MCP Clients

Claude Desktop / VS Code / Other MCP Clients

To use this server with Claude Desktop, VS Code, or any MCP-compatible client, add the following configuration to your client settings (e.g., claude_desktop_config.json or .vscode/mcp.json):

uv (local server)

{
  "mcpServers": {
    "reader": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/reader/server",
        "run",
        "main.py"
      ],
      "env": {
        "READWISE_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

  • Replace /absolute/path/to/your/reader/server with the actual path to this project directory.

  • Replace your-token-here with your actual Readwise Reader API access token.

  • Alternatively, you can specify the READWISE_ACCESS_TOKEN in an .env file located in the project directory.

For more information, see the Readwise Reader API documentation and MCP documentation.

Reader Skill

This repository also includes a standalone skill for interacting with Readwise Reader API directly via HTTP requests. The skill provides knowledge and examples for using the Reader API without requiring an MCP server.

Features

  • List, create, update, and delete documents

  • Full API coverage (list, save, update, delete, tags, bulk operations)

  • Authentication and rate limit guidance

  • Code examples in Python

Installation

npx skills add xinthink/reader-mcp-server --skill reader

For more information on installing and using skills, see the Vercel Labs Skills documentation.

Usage

Once installed, the skill will be automatically triggered when you ask about Readwise Reader, saving articles, or managing your reading list.

Available Tools

7 tools
reader_auth_checkA
Read-onlyIdempotent
Verify authentication with the Readwise Reader API.

Returns:
    AuthCheckResponse with authenticated status

Raises:
    ValueError: If authentication fails (401) or rate limited (429)

Inputs: no named parameters. Returns: authenticated

reader_bulk_update_documentsA
Bulk update multiple documents (max 50 per request).

Args:
    updates: (Required) Array of update objects. Each object must have:
        - id: (Required) Document ID to update
        - title: (Optional) New title
        - author: (Optional) New author
        - summary: (Optional) New summary
        - published_date: (Optional) Publication date (ISO 8601)
        - image_url: (Optional) Cover image URL
        - location: (Optional) New location (new, later, shortlist, archive, feed)
        - category: (Optional) New category (article, email, rss, highlight, note, pdf, epub, tweet, video)
        - tags: (Optional) Replace tags
        - notes: (Optional) Update notes
        - seen: (Optional) Mark as seen/unseen

Returns:
    BulkUpdateResponse with count and results

Inputs: updates (required). Returns: count, results

reader_create_documentA
Save a new document (URL) to your Readwise Reader library.

Args:
    url: (Required) URL to save. Can be a placeholder if no URL is available (e.g., https://yourapp.com#document1)
    html: Provide the document's content as valid HTML (Readwise will not scrape the URL)
    should_clean_html: Auto-clean HTML and parse metadata when html is provided (default: false)
    title: Override the detected title
    author: Override the detected author
    summary: Override the detected summary
    publishedDate: Publication date (ISO 8601 format)
    imageUrl: Cover image URL
    location: Where to save the document (new, later, archive, feed; default: new)
    category: Override the detected category (article, email, rss, highlight, note, pdf, epub, tweet, video)
    saved_using: Source identifier for the document (e.g., "MyApp")
    tags: List of tags to apply
    notes: Personal notes about the document

Returns:
    CreateDocumentResponse with id, url, title, and status

Inputs: url (required), html, should_clean_html, title, +9 more. Returns: id, url, title, status

reader_delete_documentA
Destructive
Delete one or more documents from your Readwise Reader library.

Args:
    ids: (Required) Array of document IDs to delete (at least one)

Returns:
    DeleteDocumentResponse with deleted count and ids

Inputs: ids (required). Returns: deleted, ids

reader_list_documentsA
Read-onlyIdempotent
List documents from your Readwise Reader library.

Args:
    id: Get a single document by ID (returns only that document)
    location: Filter by folder location (new, later, shortlist, archive, feed)
    category: Filter by category (article, email, rss, highlight, note, pdf, epub, tweet, video)
    tag: Filter by tag keys (pass empty list [] for untagged documents)
    updatedAfter: Filter by update time (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)
    limit: Number of results to return (1-100, default: 100)
    withContent: Include full HTML content in response (default: false)
    pageCursor: Pagination cursor for next page

Returns:
    ListDocumentResponse with count, results, and nextPageCursor

Inputs: id, location, category, tag, +4 more. Returns: count, results, nextPageCursor

reader_list_tagsA
Read-onlyIdempotent
List all tags from your Readwise Reader library.

Returns:
    ListTagsResponse with count and results

Inputs: no named parameters. Returns: count, results

reader_update_documentA
Update a document in your Readwise Reader library.

Args:
    id: (Required) Document ID to update
    title: New title
    author: New author
    summary: New summary
    published_date: Publication date (ISO 8601 format)
    image_url: Cover image URL
    location: New location (new, later, shortlist, archive, feed)
    category: New category (article, email, rss, highlight, note, pdf, epub, tweet, video)
    tags: Replace existing tags (note: this replaces, not appends)
    notes: Update personal notes (empty string clears notes)
    seen: Mark as seen (true) or unseen (false)

Returns:
    UpdateDocumentResponse with id, updated status, and document

Inputs: id (required), title, author, summary, +7 more. Returns: id, updated, document

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct purpose: authentication, document CRUD (create, read, update, delete), bulk update, and tag listing. No overlapping functionality.

    Naming Consistency5/5

    All tools follow the 'reader_verb_noun' snake_case pattern, e.g., reader_create_document, reader_list_documents. Consistent and predictable.

    Tool Count5/5

    Seven tools cover the core operations for the domain without excess. The count feels well-scoped and purposeful.

    Completeness5/5

    The tool set covers CRUD, bulk operations, tags, and authentication. The list_documents tool can retrieve individual documents via ID and includes content, so no major gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers