Readwise

Set up, OAuth-authenticate, and use the Readwise MCP server (mcp2.readwise.io/mcp) via the mcporter CLI. Use when a user asks to connect/auth Readwise MCP, reset or troubleshoot OAuth login (stale redirect ports, invalid state), verify the connection, or run Readwise tools through mcporter.

Security Scan

The skill's runtime instructions mostly match its Readwise/MCP purpose, but there are provenance and metadata inconsistencies and it explicitly reads local credential/config files (sensitive) without declaring that requirement — review before installing.

Purpose & Capability

The SKILL.md is clearly about controlling Readwise MCP via the mcporter CLI (auth, listing, tagging, moving docs). That purpose is coherent with the commands shown. However, the registry metadata declares no required binaries or config paths while the instructions expect the mcporter binary and a project config (config/mcporter.json) to exist — an omission in declared requirements.

Instruction Scope

Instructions are explicit about running mcporter commands and about OAuth troubleshooting. They also instruct the agent to read local files (project config at config/mcporter.json and ~/.mcporter/credentials.json) to find redirect_uris/ports. Reading those files is directly relevant to OAuth troubleshooting but it is sensitive: credentials/state may be present in ~/.mcporter/credentials.json.

Install Mechanism

This is an instruction-only skill with no install spec or code files, so nothing will be written to disk by the skill bundle itself. Lower install risk.

Credentials

The skill does not request environment variables or credentials via metadata, which is good, but the runtime instructions implicitly require access to local config/credential files (~/.mcporter/credentials.json and project config). That access is proportionate to OAuth troubleshooting and mcporter usage but is sensitive and should be expected by the user.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It will instruct mcporter to perform writes (tag/move/set notes) but the SKILL.md recommends showing a read-only plan and asking for approval before writes, which is appropriate.

What to consider before installing

This skill is instruction-only and appears to do what it says (use mcporter to manage Readwise MCP), but check these before installing: - Provenance: the source/homepage are missing. Only install if you trust the maintainer or can inspect the commands you will allow. - Local files: the skill instructs reading config/mcporter.json and ~/.mcporter/credentials.json — these may contain tokens/state. Expect the agent to access those files during OAuth troubleshooting. - mcporter binary: the metadata did not list required binaries, but the skill requires the mcporter CLI. Verify you have a trusted mcporter installed and run preflight yourself (command -v mcporter && mcporter --version). - Network endpoint: the skill targets https://mcp2.readwise.io/mcp — confirm this is the correct official endpoint for your Readwise account before authenticating. - Writes: the skill can apply changes (tag, move, set notes). The SKILL.md sensibly recommends presenting a read-only plan and asking for approval first; insist on that behavior or run write commands manually. If you are unsure, run the mcporter commands manually in a terminal (or in an isolated environment) instead of granting the agent autonomous invocation, and inspect ~/.mcporter/credentials.json for sensitive tokens before proceeding.

Readwise MCP (mcporter)

This skill is intentionally kept short. High-level workflows live in: skills/readwise-mcp/RECIPES.md.

Preflight

command -v mcporter && mcporter --version

Ensure you’re in the Clawdbot workspace root where config/mcporter.json lives.

Quick setup (first time)

# Add the server to the *project* config
mcporter config add readwise https://mcp2.readwise.io/mcp \
  --auth oauth \
  --description "Readwise MCP"

# Start OAuth login (will open a browser)
mcporter auth readwise --reset

Verify it works

mcporter list readwise --output json
mcporter call readwise.reader_list_tags --args '{}' --output json

Troubleshooting OAuth (common failure modes)

“Invalid OAuth state”

Cause: you approved in a stale browser tab (old auth attempt / old port).

Fix:

• Close old Readwise OAuth tabs.
• Re-run:

mcporter auth readwise --reset

Redirecting to an old port even after reset

Cause: browser session reuse.

Fix:

• Use Incognito/Private window.
• Or copy the new authorize URL into a fresh profile.

“Waiting for browser approval…” but you already approved

You must land on:

http://127.0.0.1:<PORT>/callback?code=...&state=...

If the redirect hits a different port, mcporter will keep waiting.

To find the expected port:

cat ~/.mcporter/credentials.json

Look for redirect_uris and ensure the browser redirect matches exactly.

Using the server

General pattern:

mcporter call readwise.<tool_name> --args '{...}' --output json

Notes:

• --args must be valid JSON (prefer single quotes in shell).
• For Reader locations: new = inbox, later, shortlist, archive, feed (RSS only).

Tool index (what’s available)

• readwise_search_highlights — search highlights (vector + optional field filters)
• reader_search_documents — search Reader documents (hybrid search)
• reader_create_document — save a URL or HTML into Reader
• reader_list_documents — list newest documents (and paginate)
• reader_get_document_details — fetch a document’s full Markdown content
• reader_get_document_highlights — fetch highlights for a document
• reader_list_tags — list tag names
• reader_add_tags_to_document / reader_remove_tags_from_document
• reader_add_tags_to_highlight / reader_remove_tags_from_highlight
• reader_set_document_notes / reader_set_highlight_notes
• reader_move_document — move between inbox/later/shortlist/archive
• reader_edit_document_metadata — edit metadata (including seen)
• reader_export_documents — export Reader docs as a ZIP

Quick examples (most-used)

1) Search highlights (idea-first / semantic)

mcporter call readwise.readwise_search_highlights \
  --args '{"vector_search_term":"incentives", "limit": 10}' \
  --output json

2) Search Reader documents (hybrid)

mcporter call readwise.reader_search_documents \
  --args '{"query":"MCP", "limit": 10}' \
  --output json

3) List newest docs in inbox (thin fields)

mcporter call readwise.reader_list_documents \
  --args '{
    "limit": 10,
    "location": "new",
    "response_fields":["title","author","url","category","location","created_at","tags"]
  }' \
  --output json

4) Get a document’s full content (markdown)

mcporter call readwise.reader_get_document_details \
  --args '{"document_id":"<id>"}' \
  --output json

Recipes

See: skills/readwise-mcp/RECIPES.md

Recipe names:

• Triage inbox (or Later fallback)
• Feed digest (last day/week) + mark as seen
• Quiz the user on a recently read archived document
• Recommendations (build a reading profile → pick next best doc)
• Library organizer (tagging + inbox-zero)

Shortlist semantics (important)

Readwise supports a shortlist location, but many people use it differently.

Default assumption (most users): inbox / later / archive

• “Shortlisting” means: add a shortlist tag AND move the doc to later.

Alternative setup: later / shortlist / archive

• “Shortlisting” means: move the doc to location=shortlist.

So: before applying any shortlisting action, confirm which setup the user uses. If unknown, assume the default (tag + move to later).

Safety / defaults

When a workflow proposes writes (tagging, moving, setting notes/seen), default to:

• show a read-only plan first (counts + which docs)
• ask for approval before applying changes