Working with the reMarkable via remarkable-mcp
remarkable-mcp is a stdio MCP server (binary at ~/.local/bin/remarkable-mcp,
uvx remarkable-mcp also works) that talks to the reMarkable cloud (or the
tablet over SSH/USB). It exposes read and write tools for documents on the
tablet.
Setup and auth
Register the server once, at user scope so it is available in every project:
claude mcp add remarkable -s user -- remarkable-mcp
claude mcp list # expect: remarkable: remarkable-mcp - ✔ Connected
Auth uses a cloud token stored in ~/.rmapi. If that file exists, the server is
already authenticated (remarkable_status reports "authenticated": true) — no
further action. To register a new device, get a one-time code from
https://my.remarkable.com/device/desktop and run:
remarkable-mcp --register <code> # prints/stores the token
Transports: cloud API by default; --ssh (developer mode) or --usb for a
directly-connected tablet; --no-cloud-fallback to forbid the cloud fallback.
Write tools (upload/mkdir/move/rename/delete) are on by default; pass
--read-only to expose a read-only server.
Tool inventory
| Tool |
Purpose |
Key args |
remarkable_status |
auth/transport/capabilities, document count |
— |
remarkable_browse |
list a folder / filter |
path, query, tags |
remarkable_recent |
most recently modified docs |
limit, include_preview |
remarkable_search |
find a doc; returns path + page OCR text |
query, grep, limit, include_ocr |
remarkable_read |
page text / OCR; content_type=annotations lists annotated pages + highlighted text |
document, page, content_type, include_ocr |
remarkable_image |
render a page to PNG; render_merged=true composites PDF + strokes + highlights |
document, page, render_merged, output_format |
remarkable_canvas |
interactive canvas render of a page |
document, page |
remarkable_upload |
upload a local file |
file_path (req), parent_folder, document_name |
remarkable_mkdir / move / rename / delete |
manage docs/folders |
see schema |
Get exact schemas at runtime with tools/list (see the script below).
Reading annotations: merged render + highlight/notes extraction
Requires the patched build — the fixes below live on the
fix/render-merged-imported-pdfs branch of ~/devel/remarkable-mcp, installed
editable via uv tool install --editable ~/devel/remarkable-mcp --force. The
PyPI remarkable-mcp (≤ 1.0.0) still has the bugs listed under "Unpatched
release" — check with uv tool list (a file:// / local version = patched).
With the patched build:
- Composite an annotated page:
remarkable_image(document, page, render_merged=True) returns one PNG with the PDF page + pen strokes + text
highlights at correct positions (PNG only; the page needs a PDF underlay).
Save the blob and Read it (see the resource-blob gotcha).
- Find/extract annotations without scanning every page:
remarkable_read(document, content_type="annotations") returns an "Annotated
pages" section — only the pages that carry annotations, each showing whether
it has handwritten notes and its highlighted text. The underlying
extraction result also exposes highlights (flat list) and annotated_pages
([{page, page_id, has_handwriting, highlights}], 1-based page numbers).
Highlight text is the reMarkable's stored text selection: great for locating
annotated passages, but occasionally glitchy (a dropped letter, or a sentence
split across entries) — treat it as a finder, not a verbatim transcript.
Unpatched release (PyPI ≤ 1.0.0): use the native email export
On the release build, render_merged is broken for imported PDFs
(formatVersion-1 docs render annotation-only; the coordinate transform
mis-places ink — single strokes off-position, multi-stroke pages fill solid
black), text highlights never render, and content_type=annotations returns no
highlights. For correct output there, use reMarkable's own on-device export:
- Tablet: open the document → Page overview → long-press the page → ⋯
(More) → Send by email → PDF (or PNG) → send to the user's own
address.
- Retrieve it via a connected Gmail/mail MCP (
claude mcp list to check) — pull
the attachment — or ask the user to share the file. Then Read it; positions
are exact because reMarkable rendered it. You cannot trigger this export
headlessly (no cloud endpoint); the user taps once, you fetch and read.
Gotchas (learned the hard way — read before using)
Address documents by PATH or name, not the upload UUID. remarkable_upload
returns a uuid, but remarkable_read/remarkable_image look up by path
(e.g. /My Paper (draft)) or name — passing the uuid gives
document_not_found. After uploading, call remarkable_search/remarkable_recent
to get the path, then use that.
Pages are 1-based. page=0 → page_out_of_range ("use page=1 to N").
Mid-session claude mcp add (or reinstalling the tool) does not reach the
current session. claude mcp list shows ✔ Connected, but the
mcp__remarkable__* tools — and any freshly-installed build — are only picked
up at session start, so ToolSearch won't find the tools until a new
session. To act immediately in the same session, drive the stdio server
directly with scripts/rm_mcp.py (a JSON-RPC client).
Annotations only exist in the cloud once the tablet has synced. A layer
made on the device is invisible to the cloud API until the tablet syncs up.
Signs it hasn't: the document's modified time still equals the upload time;
render_merged/content_type=annotations show no ink or highlights. Do not
conclude there is no annotation — ask the user to sync (Wi-Fi, wake the device
/ manual sync), then retry.
Image results come back as an MCP resource blob. In the tools/call
result, content[] holds an item of type resource with base64 in
resource.blob (or type image with data). Save those bytes to a .png
and Read it. Do not rely on resources/read of the remarkableimg:///…
URI — spaces/parentheses in document names break it ("unbalanced
parenthesis"); use the inline blob from tools/call instead. Note some modes
(compatibility=true) return the PNG as a data:image/png;base64,… string in
a data_uri JSON field instead — handle that shape too.
Driving the server directly (in-session fallback)
When the MCP tools are not yet loaded (gotcha 3), or for scripted/batch use, run
scripts/rm_mcp.py. It speaks the newline-delimited JSON-RPC stdio protocol
(initialize → notifications/initialized → tools/call) and handles saving
image blobs to files.
# discover tools and schemas
scripts/rm_mcp.py list
# status / find a just-uploaded doc's path
scripts/rm_mcp.py call remarkable_status
scripts/rm_mcp.py call remarkable_recent '{"limit":5}'
# upload a PDF (root folder)
scripts/rm_mcp.py call remarkable_upload \
'{"file_path":"/abs/path/article.pdf","document_name":"My Paper (draft)"}'
# render page 1 with annotations composited onto the PDF (patched build)
scripts/rm_mcp.py render "/My Paper (draft)" 1 out.png
# list annotated pages + highlighted text
scripts/rm_mcp.py call remarkable_read \
'{"document":"/My Paper (draft)","content_type":"annotations"}'
Then Read the saved PNG. On the patched build render composites the page + ink
- highlights at correct positions; on the unpatched release it returns only the
(cropped, possibly mis-placed) ink layer — see the version note above. The script
is small and provider-agnostic; read it before extending.
Verify an upload
remarkable_upload returns "uploaded": true with a uuid; confirm it landed
with remarkable_recent/remarkable_search (the cloud may take a moment to
index). It syncs to the physical device when the tablet is online.
Versioned review workflow (send a draft, iterate, keep history)
The common loop is: send a document to the tablet, the user reviews and
annotates it there, you read the annotations, revise the source, and send
the revised build back. Do it as a versioned trail, not an overwrite.
Why this matters: remarkable_upload to the cloud is add-only — it
never replaces. Re-uploading a revised PDF under the same name creates a
second document with that same name, not a new revision of the first. So
uploads naturally accumulate; embrace that instead of fighting it.
The workflow, unless the user says otherwise:
- Bake the version — and the branch — into the name at upload time.
Every upload gets a unique
document_name with date and version:
"<Title> (draft YYYY-MM-DD, vN)" on the default branch (the vt-debug
paper's convention; "<Title> (review vN)" works for non-drafts), and
"<Title> (<branch>, draft YYYY-MM-DD, vN)" when the build comes from a
feature branch or worktree — e.g. learnlog (metrics, draft 2026-08-31, v8). Take <branch> from git branch --show-current, dropping a
worktree- prefix, so the user can tell on the tablet which line of
work a draft belongs to and two branches' drafts do not interleave
silently in one version sequence. <Title> is the existing document
family's name — before the first upload in a session, run
remarkable_browse(query="<title word>") and reuse the family name and
its highest vN; inventing a new family ("learnlog documentation (metrics, …, v1)" beside an existing "learnlog (draft …, v7)")
breaks the version trail and costs a rename. Because no two uploads
share a name, there is no rename step and no name-collision
ambiguity — every later tool call addresses the document by its
unique name. Never upload under a bare base name planning to rename
afterwards.
- Leave the earlier versions in place. The tablet then holds the
whole review history, each version distinguishable at a glance, and
the user can compare against their earlier annotations. Do not
delete or overwrite prior versions unless the user asks (a version
superseded within minutes, before the user opened it, is fair to offer
to delete — still ask).
- Pick N by incrementing the last uploaded version — from the
conversation, the repo's commit messages (pairing each upload with its
commit, message noting "uploaded as draft YYYY-MM-DD, vN", keeps this
trail in git), or by
remarkable_search-ing the title and taking the
highest existing suffix across all branches (one counter per
document family, not per branch, so v8 on a feature branch follows v7
from main and a later main build is v9). Version numbers are cheap: a
same-day follow-up change gets vN+1, never a silent re-upload of vN.
- Read annotations from the version the user reviewed — usually the
latest, but if they name an older draft, read that one. Before
concluding a version has no annotations, remember the sync trap
(gotcha 4): ask the user to sync rather than report "no comments".
If you did end up with two documents sharing a name (e.g. an upload
that was meant to replace): rename by path/name, never the upload UUID
(gotcha 1 — the UUID lookup fails). remarkable_browse/_recent lists
the most recently modified first, so the fresh upload is the first
match and rename-by-name targets it — but verify afterward: re-browse
and check that the new name landed on the entry whose modified time is
the newest, not on an older version.
If the user instead wants a single evolving document (no history), the
add-only cloud API can't update in place — delete the prior version after a
successful new upload (ask first; deletion is destructive), or keep one
name and let them tell versions apart by modified date.
For research papers, the surrounding loop (read all annotated pages, apply
the round, rebuild, one commit per round named after the draft, push,
upload the next version) is owned by the scientific-writing skill;
this section owns only the tablet mechanics.
1---2name: remarkable3description: "IMPORTANT: load this skill BEFORE calling ANY remarkable-mcp tool — even a one-line upload — because the tools have silent-failure gotchas (address docs by path/name, NOT the UUID that upload returns; annotations only appear after the tablet syncs; render_merged needs the patched build). Work with a reMarkable tablet via the remarkable-mcp MCP server: upload PDFs/EPUBs, browse/search the cloud, render pages (optionally compositing annotations onto the PDF), read page text/OCR, extract highlighted text, and list which pages carry notes/highlights. Use when: (1) sending/uploading a document, paper, or PDF to the reMarkable ('put this on my reMarkable', 'upload to remarkable'); (2) reading/rendering/checking an annotation, note, or highlight, or extracting only the annotated pages; (3) the user mentions reMarkable, remarkable-mcp, rmapi, or their tablet; (4) setting up or troubleshooting the server. Covers auth, the tool inventory, annotation extraction, and more gotchas (1-based pages, mid-session MCP loading)."4metadata:5 source: https://skillmd.com/skills/dbosk/remarkable6---78# Working with the reMarkable via remarkable-mcp910`remarkable-mcp` is a stdio MCP server (binary at `~/.local/bin/remarkable-mcp`,11`uvx remarkable-mcp` also works) that talks to the reMarkable cloud (or the12tablet over SSH/USB). It exposes read and write tools for documents on the13tablet.1415## Setup and auth1617Register the server once, at **user** scope so it is available in every project:1819```bash20claude mcp add remarkable -s user -- remarkable-mcp21claude mcp list # expect: remarkable: remarkable-mcp - ✔ Connected22```2324Auth uses a cloud token stored in `~/.rmapi`. If that file exists, the server is25already authenticated (`remarkable_status` reports `"authenticated": true`) — no26further action. To register a new device, get a one-time code from27`https://my.remarkable.com/device/desktop` and run:2829```bash30remarkable-mcp --register <code> # prints/stores the token31```3233Transports: cloud API by default; `--ssh` (developer mode) or `--usb` for a34directly-connected tablet; `--no-cloud-fallback` to forbid the cloud fallback.35Write tools (upload/mkdir/move/rename/delete) are **on by default**; pass36`--read-only` to expose a read-only server.3738## Tool inventory3940| Tool | Purpose | Key args |41|------|---------|----------|42| `remarkable_status` | auth/transport/capabilities, document count | — |43| `remarkable_browse` | list a folder / filter | `path`, `query`, `tags` |44| `remarkable_recent` | most recently modified docs | `limit`, `include_preview` |45| `remarkable_search` | find a doc; returns `path` + page OCR text | `query`, `grep`, `limit`, `include_ocr` |46| `remarkable_read` | page text / OCR; `content_type=annotations` lists annotated pages + highlighted text | `document`, `page`, `content_type`, `include_ocr` |47| `remarkable_image` | render a page to PNG; `render_merged=true` composites PDF + strokes + highlights | `document`, `page`, `render_merged`, `output_format` |48| `remarkable_canvas` | interactive canvas render of a page | `document`, `page` |49| `remarkable_upload` | upload a local file | `file_path` (req), `parent_folder`, `document_name` |50| `remarkable_mkdir` / `move` / `rename` / `delete` | manage docs/folders | see schema |5152Get exact schemas at runtime with `tools/list` (see the script below).5354## Reading annotations: merged render + highlight/notes extraction5556**Requires the patched build** — the fixes below live on the57`fix/render-merged-imported-pdfs` branch of `~/devel/remarkable-mcp`, installed58editable via `uv tool install --editable ~/devel/remarkable-mcp --force`. The59PyPI `remarkable-mcp` (≤ 1.0.0) still has the bugs listed under "Unpatched60release" — check with `uv tool list` (a `file://` / local version = patched).6162With the patched build:6364- **Composite an annotated page:** `remarkable_image(document, page,65 render_merged=True)` returns one PNG with the **PDF page + pen strokes + text66 highlights** at correct positions (PNG only; the page needs a PDF underlay).67 Save the blob and Read it (see the resource-blob gotcha).68- **Find/extract annotations without scanning every page:**69 `remarkable_read(document, content_type="annotations")` returns an **"Annotated70 pages"** section — only the pages that carry annotations, each showing whether71 it has handwritten notes and its **highlighted text**. The underlying72 extraction result also exposes `highlights` (flat list) and `annotated_pages`73 (`[{page, page_id, has_handwriting, highlights}]`, 1-based page numbers).7475Highlight text is the reMarkable's stored text selection: great for *locating*76annotated passages, but occasionally glitchy (a dropped letter, or a sentence77split across entries) — treat it as a finder, not a verbatim transcript.7879### Unpatched release (PyPI ≤ 1.0.0): use the native email export80On the release build, `render_merged` is broken for imported PDFs81(formatVersion-1 docs render annotation-only; the coordinate transform82mis-places ink — single strokes off-position, multi-stroke pages fill solid83black), text highlights never render, and `content_type=annotations` returns no84highlights. For correct output there, use reMarkable's **own on-device export**:85861. Tablet: open the document → **Page overview** → long-press the page → **⋯87 (More)** → **Send by email** → **PDF** (or **PNG**) → send to the user's own88 address.892. Retrieve it via a connected Gmail/mail MCP (`claude mcp list` to check) — pull90 the attachment — or ask the user to share the file. Then Read it; positions91 are exact because reMarkable rendered it. You **cannot** trigger this export92 headlessly (no cloud endpoint); the user taps once, you fetch and read.9394## Gotchas (learned the hard way — read before using)95961. **Address documents by PATH or name, not the upload UUID.** `remarkable_upload`97 returns a `uuid`, but `remarkable_read`/`remarkable_image` look up by path98 (e.g. `/My Paper (draft)`) or name — passing the uuid gives99 `document_not_found`. After uploading, call `remarkable_search`/`remarkable_recent`100 to get the `path`, then use that.1011022. **Pages are 1-based.** `page=0` → `page_out_of_range` ("use page=1 to N").1031043. **Mid-session `claude mcp add` (or reinstalling the tool) does not reach the105 current session.** `claude mcp list` shows `✔ Connected`, but the106 `mcp__remarkable__*` tools — and any freshly-installed build — are only picked107 up at session start, so `ToolSearch` won't find the tools until a **new**108 session. To act immediately in the same session, drive the stdio server109 directly with `scripts/rm_mcp.py` (a JSON-RPC client).1101114. **Annotations only exist in the cloud once the tablet has synced.** A layer112 made on the device is invisible to the cloud API until the tablet syncs up.113 Signs it hasn't: the document's `modified` time still equals the upload time;114 `render_merged`/`content_type=annotations` show no ink or highlights. Do not115 conclude there is no annotation — ask the user to sync (Wi-Fi, wake the device116 / manual sync), then retry.1171185. **Image results come back as an MCP resource blob.** In the `tools/call`119 result, `content[]` holds an item of type `resource` with base64 in120 `resource.blob` (or type `image` with `data`). Save those bytes to a `.png`121 and Read it. Do **not** rely on `resources/read` of the `remarkableimg:///…`122 URI — spaces/parentheses in document names break it ("unbalanced123 parenthesis"); use the inline blob from `tools/call` instead. Note some modes124 (`compatibility=true`) return the PNG as a `data:image/png;base64,…` string in125 a `data_uri` JSON field instead — handle that shape too.126127## Driving the server directly (in-session fallback)128129When the MCP tools are not yet loaded (gotcha 3), or for scripted/batch use, run130`scripts/rm_mcp.py`. It speaks the newline-delimited JSON-RPC stdio protocol131(`initialize` → `notifications/initialized` → `tools/call`) and handles saving132image blobs to files.133134```bash135# discover tools and schemas136scripts/rm_mcp.py list137138# status / find a just-uploaded doc's path139scripts/rm_mcp.py call remarkable_status140scripts/rm_mcp.py call remarkable_recent '{"limit":5}'141142# upload a PDF (root folder)143scripts/rm_mcp.py call remarkable_upload \144 '{"file_path":"/abs/path/article.pdf","document_name":"My Paper (draft)"}'145146# render page 1 with annotations composited onto the PDF (patched build)147scripts/rm_mcp.py render "/My Paper (draft)" 1 out.png148149# list annotated pages + highlighted text150scripts/rm_mcp.py call remarkable_read \151 '{"document":"/My Paper (draft)","content_type":"annotations"}'152```153154Then Read the saved PNG. On the patched build `render` composites the page + ink155+ highlights at correct positions; on the unpatched release it returns only the156(cropped, possibly mis-placed) ink layer — see the version note above. The script157is small and provider-agnostic; read it before extending.158159## Verify an upload160161`remarkable_upload` returns `"uploaded": true` with a uuid; confirm it landed162with `remarkable_recent`/`remarkable_search` (the cloud may take a moment to163index). It syncs to the physical device when the tablet is online.164165## Versioned review workflow (send a draft, iterate, keep history)166167The common loop is: send a document to the tablet, the user reviews and168annotates it there, you read the annotations, revise the source, and send169the revised build back. Do it as a **versioned trail**, not an overwrite.170171**Why this matters:** `remarkable_upload` to the cloud is **add-only — it172never replaces**. Re-uploading a revised PDF under the same name creates a173*second* document with that same name, not a new revision of the first. So174uploads naturally accumulate; embrace that instead of fighting it.175176The workflow, unless the user says otherwise:1771781. **Bake the version — and the branch — into the name at upload time.**179 Every upload gets a unique `document_name` with date and version:180 `"<Title> (draft YYYY-MM-DD, vN)"` on the default branch (the vt-debug181 paper's convention; `"<Title> (review vN)"` works for non-drafts), and182 `"<Title> (<branch>, draft YYYY-MM-DD, vN)"` when the build comes from a183 feature branch or worktree — e.g. `learnlog (metrics, draft 2026-08-31,184 v8)`. Take `<branch>` from `git branch --show-current`, dropping a185 `worktree-` prefix, so the user can tell on the tablet which line of186 work a draft belongs to and two branches' drafts do not interleave187 silently in one version sequence. `<Title>` is the **existing document188 family's name** — before the first upload in a session, run189 `remarkable_browse(query="<title word>")` and reuse the family name and190 its highest vN; inventing a new family (`"learnlog documentation191 (metrics, …, v1)"` beside an existing `"learnlog (draft …, v7)"`)192 breaks the version trail and costs a rename. Because no two uploads193 share a name, there is **no rename step and no name-collision194 ambiguity** — every later tool call addresses the document by its195 unique name. Never upload under a bare base name planning to rename196 afterwards.1972. **Leave the earlier versions in place.** The tablet then holds the198 whole review history, each version distinguishable at a glance, and199 the user can compare against their earlier annotations. Do **not**200 delete or overwrite prior versions unless the user asks (a version201 superseded within minutes, before the user opened it, is fair to offer202 to delete — still ask).2033. **Pick N by incrementing the last uploaded version** — from the204 conversation, the repo's commit messages (pairing each upload with its205 commit, message noting "uploaded as draft YYYY-MM-DD, vN", keeps this206 trail in git), or by `remarkable_search`-ing the title and taking the207 highest existing suffix **across all branches** (one counter per208 document family, not per branch, so v8 on a feature branch follows v7209 from main and a later main build is v9). Version numbers are cheap: a210 same-day follow-up change gets vN+1, never a silent re-upload of vN.2114. **Read annotations from the version the user reviewed** — usually the212 latest, but if they name an older draft, read that one. Before213 concluding a version has no annotations, remember the sync trap214 (gotcha 4): ask the user to sync rather than report "no comments".215216**If you did end up with two documents sharing a name** (e.g. an upload217that was meant to replace): rename by path/name, never the upload UUID218(gotcha 1 — the UUID lookup fails). `remarkable_browse`/`_recent` lists219the **most recently modified first**, so the fresh upload is the first220match and rename-by-name targets it — but **verify afterward**: re-browse221and check that the new name landed on the entry whose `modified` time is222the newest, not on an older version.223224If the user instead wants a single evolving document (no history), the225add-only cloud API can't update in place — delete the prior version after a226successful new upload (ask first; deletion is destructive), or keep one227name and let them tell versions apart by modified date.228229For research papers, the surrounding loop (read all annotated pages, apply230the round, rebuild, one commit per round named after the draft, push,231upload the next version) is owned by the **scientific-writing** skill;232this section owns only the tablet mechanics.