> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Readwise MCP server

The Readwise MCP connector routes your AI agent's tool calls to Readwise's own MCP server through Scalekit. Each user signs in to Readwise once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 22 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** Productivity
**Tools:** 22: 9 read, 6 write, 7 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Readwise MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=READWISEMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Readwise MCP connection

   In **AgentKit > Connections**, create a Readwise MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Readwise MCP server connections use your own OAuth app. Register one with Readwise MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Readwise MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'readwisemcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Readwise MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'readwisemcp_reader_list_documents',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "readwisemcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Readwise MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="readwisemcp_reader_list_documents",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'readwisemcp_reader_get_document_details',
  toolInput: {
    document_id: '<document_id>',
  },
  connector: 'readwisemcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="readwisemcp_reader_get_document_details",
    tool_input={
        "document_id": "<document_id>",
    },
    connection_name="readwisemcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `readwisemcp_reader_get_document_details`

Get Reader document details · Read-only

Get Reader document details, including Markdown content

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `document_id` (`string`, required): The ID of the document to get details for

Example input: `{"document_id":"<document_id>"}`

### `readwisemcp_reader_get_document_highlights`

Get Reader document highlights · Read-only

Get highlights for a Reader document

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `document_id` (`string`, required): The ID of the document to get highlights for

Example input: `{"document_id":"<document_id>"}`

### `readwisemcp_reader_get_export_documents_status`

Check Reader export status · Read-only

Check the status of a previously triggered Reader document export. Returns `status` ('processing' or 'completed'), progress counts, and a `download_url` when the export is complete.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `export_id` (`string`, required): The export ID returned by `reader_export_documents`.

Example input: `{"export_id":"<export_id>"}`

### `readwisemcp_reader_list_documents`

List Reader documents · Read-only

List Reader documents. Documents are returned from the most recently added to the least recently added. This tool can be used to find N newest documents. Tip: unseen documents have first_opened_at=null, seen documents have a non-null first_opened_at. You can mark documents as seen with reader_bulk_edit_document_metadata(documents=[{document_id: ..., seen: true}]). Tip: for videos (e.g. YouTube) and podcasts, word_count and reading_time are null; use listening_time (duration formatted like reading_time, e.g. '13 mins') instead.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Filter by document category. One of: `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet`, `video`, `podcast`, `audiobook`.
- `id` (`string`, optional): The document's unique ID. Using this parameter will return just one document, if found.
- `limit` (`integer`, optional): The maximum number of documents to return. Default: `10`.
- `location` (`string`, optional): Filter by document location. 'new' = inbox (where newly saved documents go), 'later' = saved for later, 'shortlist' = shortlisted, 'archive' = archived, 'feed' = RSS feed items (only use when user explicitly asks about feed/RSS). When user says 'inbox', use 'new'. One of: `new`, `later`, `shortlist`, `archive`, `feed`.
- `page_cursor` (`string`, optional): A string returned by a previous request to get the next page of documents
- `response_fields` (`array`, optional): Optional fields to include in each document result. The 'id' field is always included. If not specified, all fields except the full-body 'content' and 'html_content' are included, since a single document body can be 100k+ characters. Request 'content'/'html_content' explicitly here (or use reader_get_document_details) only when you need the full text of the listed documents.
- `seen` (`boolean`, optional): Filter by seen status. True = only documents that have been opened, False = only unopened documents.
- `tag` (`array`, optional): Filter by tag(s). Pass up to 5 tags to find documents having all the tags listed. Pass empty string in the list to find untagged documents.
- `updated_after` (`string`, optional): Fetch only documents updated after this date (ISO 8601 datetime)

Example input: `{}`

### `readwisemcp_reader_list_tags`

List Reader tags · Read-only

List Reader tags

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `readwisemcp_reader_search_documents`

Search Reader documents · Read-only

Search Reader documents using hybrid search

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Search in document content
- `author_search` (`string`, optional): Search document author
- `category_in` (`array`, optional): Restrict search to specific categories
- `document_id` (`string`, optional): Restrict search to a specific document
- `limit` (`integer`, optional): The maximum number of documents to return. Default: `20`.
- `location_in` (`array`, optional): Restrict search to specific locations. Values: 'new' (inbox), 'later', 'shortlist', 'archive'. When user says 'inbox', use ['new']. This tool does not search the feed, only locations in the user's library.Defaults to ["new", "later", "shortlist", "archive"].
- `note_search` (`string`, optional): Search in document notes
- `published_date` (`string`, optional): Search by published date (ISO 8601 date)
- `published_date_gt` (`string`, optional): Search by published date greater than (ISO 8601 date)
- `published_date_gte` (`string`, optional): Search by published date greater than or equal to (ISO 8601 date)
- `published_date_lt` (`string`, optional): Search by published date less than (ISO 8601 date)
- `published_date_lte` (`string`, optional): Search by published date less than or equal to (ISO 8601 date)
- `source_search` (`string`, optional): Search in document source
- `summary_search` (`string`, optional): Search in document summary
- `tags_in` (`array`, optional): Restrict search to specific tags
- `tags_search` (`string`, optional): Search in document tags
- `title_search` (`string`, optional): Search in document title
- `url_search` (`string`, optional): Search in document URL

Example input: `{"query":"<query>"}`

### `readwisemcp_readwise_get_daily_review`

Get Readwise daily review · Read-only

Get the user's daily review of highlights. Returns today's review with all highlights selected for review by the spaced repetition algorithm. Includes the review URL where the user can complete the review interactively.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `readwisemcp_readwise_list_highlights`

List Readwise highlights · Read-only

List Readwise highlights with optional filters. Highlights are returned from the most recently added to the least recently added. This tool can be used to find N newest highlights. Use `response_fields` to control which fields are returned — omit it for the default set (all base highlight fields, no book detail), or pass a subset (and optionally any book_* field) to minimize the response and include parent-book metadata.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `book_id` (`integer`, optional): Filter by book ID
- `highlighted_at_gt` (`string`, optional): Filter highlights created after this datetime (ISO 8601)
- `highlighted_at_lt` (`string`, optional): Filter highlights created before this datetime (ISO 8601)
- `page` (`integer`, optional): Page number for pagination
- `page_size` (`integer`, optional): Number of highlights per page. Default: `100`.
- `response_fields` (`array`, optional): Fields to include on each highlight result. Use this to reduce response size and save tokens. The 'id' field is always included. If not specified, every base highlight field is returned (including 'book_id') but no book-detail fields (book_title, book_author, ...) are fetched. Requesting any book-detail field enriches each highlight with its parent book's metadata in the same request.
- `updated_gt` (`string`, optional): Filter highlights updated after this datetime (ISO 8601)
- `updated_lt` (`string`, optional): Filter highlights updated before this datetime (ISO 8601)

Example input: `{}`

### `readwisemcp_readwise_search_highlights`

Search Readwise highlights · Read-only

Search Readwise highlights

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `vector_search_term` (`string`, required): Searches document content using vector search
- `full_text_queries` (`array`, optional): Optional field targeted full text search queries
- `limit` (`integer`, optional): The maximum number of highlights to return. Default: `30`.

Example input: `{"vector_search_term":"<vector_search_term>"}`

### `readwisemcp_reader_add_tags_to_document`

Add tags to Reader document · Write

Add tags to a Reader document

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document to add tags to
- `tag_names` (`array`, required): The tag names to add to the document

Example input: `{"document_id":"<document_id>","tag_names":[]}`

### `readwisemcp_reader_add_tags_to_highlight`

Add tags to Reader highlight · Write

Add tags to a Reader document highlight

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document containing the highlight
- `highlight_document_id` (`string`, required): The ID of the highlight document to add tags to
- `tag_names` (`array`, required): The tag names to add to the document

Example input: `{"document_id":"<document_id>","highlight_document_id":"<highlight_document_id>","tag_names":[]}`

### `readwisemcp_reader_create_document`

Save document to Reader · Write

Save a new document to Reader

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `author` (`string`, optional): The document's author, overwrites the original author
- `category` (`string`, optional): The document category. Default is guessed based on the URL, usually article. One of: `article`, `email`, `rss`, `pdf`, `epub`, `tweet`, `video`, `podcast`, `audiobook`.
- `html` (`string`, optional): The content of the document in HTML format. Use `markdown` instead if you have Markdown content. If not provided, Reader will try to scrape the URL.
- `image_url` (`string`, optional): An image URL to use as cover image
- `language` (`string`, optional): Language code for the document. When omitted, Reader will auto-detect it.
- `markdown` (`string`, optional): The content of the document in Markdown format. Use `html` instead if you have HTML content.
- `notes` (`string`, optional): A top-level note for the document
- `published_date` (`string`, optional): When the document was published in ISO 8601 format
- `summary` (`string`, optional): Summary of the document
- `tags` (`array`, optional): A list of tags to apply to the document
- `title` (`string`, optional): The document's title, overwrites the original title. Should be provided when `html` is provided.
- `url` (`string`, optional): The unique URL of the document. If you don't have one, you can provide a made up value such as https://yourapp.com#document1

Example input: `{}`

### `readwisemcp_reader_create_highlight`

Create Reader highlight · Write

Create a new highlight on a document by specifying the exact text to highlight

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document to highlight
- `html_content` (`string`, required): The passage to highlight, copied verbatim from the document text. Whitespace may differ, but every other character must match -- do NOT reformat, paraphrase, trim or change any characters.
- `note` (`string`, optional): Optional note to attach to the highlight
- `tags` (`array`, optional): Optional tag names to apply to the highlight

Example input: `{"document_id":"<document_id>","html_content":"<html_content>"}`

### `readwisemcp_reader_export_documents`

Export Reader documents · Write

Export all Reader documents as a ZIP file containing Markdown files with YAML frontmatter. This tool triggers the export and returns immediately with an `export_id`. Use `reader_get_export_documents_status` to poll for completion and get the download URL. The response includes `last_updated` which can be saved and passed as `since_updated` in a future export to only include documents updated since this export.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `since_updated` (`string`, optional): Optional timestamp for delta exports. Only documents updated after this timestamp will be included. Use `last_updated` from a previous export.

Example input: `{}`

### `readwisemcp_readwise_create_highlights`

Create Readwise highlights · Write

Create one or more highlights in Readwise. When creating a Reader document highlight, use reader_create_highlight instead. Each highlight can be from the same or multiple books/articles. If you don't include a title, we'll put the highlight in a generic 'Quotes' book. If you don't include an author we'll keep it blank or just use the URL domain (if a source_url was provided). We de-dupe highlights by title/author/text/source_url. We'll put the created highlights in a book, based on the title/author/source_url combination.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `highlights` (`array`, required): List of highlights to create

Example input: `{"highlights":[]}`

### `readwisemcp_reader_bulk_edit_document_metadata`

Bulk edit Reader document metadata · Destructive

Edit metadata fields such as title, author, summary, language, seen status, location, category, tags, and notes for one or more Reader documents in a single call. Max 50 documents per call. Bulk update calls are rate-limited to 20 per minute (shared with reader_move_documents) — batch documents into fewer calls instead of calling once per document. Check the result success flags to confirm all documents have been edited successfully.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `documents` (`array`, required): List of documents to edit, each with a document_id and the metadata fields to update

Example input: `{"documents":[]}`

### `readwisemcp_reader_move_documents`

Move Reader documents · Destructive

Move one or more Reader documents to a different location (e.g. archive, later, shortlist). Max 50 documents per call. Bulk update calls are rate-limited to 20 per minute (shared with reader_bulk_edit_document_metadata) — batch document IDs into fewer calls instead of calling once per document. Check the result success flags to confirm all documents have been moved successfully.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `document_ids` (`array`, required): The IDs of the documents to move
- `location` (`string`, required): The new location for the documents. One of: `new`, `later`, `shortlist`, `archive`, `feed`.

Example input: `{"document_ids":[],"location":"new"}`

### `readwisemcp_reader_remove_tags_from_document`

Remove tags from Reader document · Destructive

Remove tags from a Reader document

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document to remove tags from
- `tag_names` (`array`, required): The tag names to remove from the document

Example input: `{"document_id":"<document_id>","tag_names":[]}`

### `readwisemcp_reader_remove_tags_from_highlight`

Remove tags from Reader highlight · Destructive

Remove tags from a Reader document highlight

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document containing the highlight
- `highlight_document_id` (`string`, required): The ID of the highlight document to remove tags from
- `tag_names` (`array`, required): The tag names to remove from the document

Example input: `{"document_id":"<document_id>","highlight_document_id":"<highlight_document_id>","tag_names":[]}`

### `readwisemcp_reader_set_highlight_notes`

Set notes on Reader highlight · Destructive

Set notes for a Reader document highlight

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `document_id` (`string`, required): The ID of the document containing the highlight
- `highlight_document_id` (`string`, required): The ID of the highlight document to set notes for
- `notes` (`string`, optional): The notes to set for the highlight. Pass null to clear the notes.

Example input: `{"document_id":"<document_id>","highlight_document_id":"<highlight_document_id>"}`

### `readwisemcp_readwise_delete_highlight`

Delete Readwise highlight · Destructive

Delete a Readwise highlight

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `highlight_id` (`integer`, required): The ID of the highlight to delete

Example input: `{"highlight_id":1}`

### `readwisemcp_readwise_update_highlight`

Update Readwise highlight · Destructive

Update a Readwise highlight. Supports adding and removing tags in a single call.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `highlight_id` (`integer`, required): The ID of the highlight to update
- `add_tags` (`array`, optional): Tag names to add to the highlight
- `color` (`string`, optional): New color for the highlight. One of: `yellow`, `blue`, `pink`, `orange`, `green`, `purple`.
- `location` (`integer`, optional): New location for the highlight
- `note` (`string`, optional): New note for the highlight
- `remove_tags` (`array`, optional): Tag names to remove from the highlight (matched by name)
- `text` (`string`, optional): New text for the highlight
- `url` (`string`, optional): New URL for the highlight

Example input: `{"highlight_id":1}`

## Related

Other Productivity connectors ([all 203](/agentkit/connectors/?category=productivity)):

- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Notion](/agentkit/connectors/notion/): Scalekit connector, OAuth, 51 tools
- [Google Workspace (DWD)](/agentkit/connectors/googledwd/): Scalekit connector, Service account, 100 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
