Skip to main content
Glama

Scriptorium

Your reMarkable library, on your own server, readable by Claude.

Scriptorium is a self-hosted MCP server that mirrors a reMarkable cloud library to local storage, keeps a durable, versioned archive of every notebook (including ones the free tier stops syncing), transcribes handwriting with Claude on demand, pushes documents back to the tablet, and can restore a wiped tablet from the archive — all through tools any Claude client can call.

Status: 0.1 (pre-1.0). The archive, reading tools, OCR and search work; push and restore are still to come (see the changelog). The architecture is in docs/Architecture.md; spikes and milestones are in docs/Plan/.

Not affiliated with reMarkable AS. The reMarkable cloud API is unofficial and may change without notice.

What it does

Area

Tools (abridged)

Notes

Archive

background sync worker

Polls the reMarkable cloud per user; stores documents in the tablet's own on-disk format with original UUIDs; keeps every superseded version; deletions become tombstones that are never purged automatically

Read & search

list, recent, search, read_page, read_document, page_image, versions

Works from claude.ai (web, Desktop, mobile) and Claude Code with one identity

OCR

transcribe, save_transcript, set_auto_ocr

Three billing modes: a per-user Claude API key, a server-wide key (per-user and global spend caps), or lazy transcription inside your own Claude session

Push

push_markdown, push_file, push_ink

Markdown → PDF, PDF/EPUB by URL, images/SVG/PDF → native ink (optional sidecar). Conversion happens on the server, so it works from a phone

Restore

snapshots, trash, restore, export

Rebuilds a wiped tablet (folders included) through the cloud, resumably and without duplicates; no cable, no developer mode

Multi-user

OAuth 2.1 via your own identity provider

Bring your own OIDC issuer; each login gets isolated storage and its own reMarkable link; users are allow-listed; admin tools are role-gated

Related MCP server: rm-brain MCP server

How it works

Paper Pro Move ⇄ reMarkable cloud ⇄ Scriptorium (Docker) ⇄ Claude clients
                                        │
                                        ├─ worker: poll · archive · render · OCR
                                        ├─ server: Streamable HTTP MCP at /mcp
                                        └─ your OIDC issuer (Keycloak optional)
  • Identity: Scriptorium is an OAuth 2.1 resource server and ships no identity provider. Point SCRIPTORIUM_OIDC_ISSUER at the issuer you already run (Keycloak, Authentik, Zitadel, Auth0, Okta, Entra ID…) and register two public PKCE clients for Claude; the exact requirements are in Architecture §5.2. A Keycloak compose profile with a ready-made realm is included for operators who have none. A Scriptorium user is an identity at that issuer, so two Claude accounts logging in as the same user share one library.

  • Linking a tablet: call connect_remarkable(code) with a one-time code from https://my.remarkable.com/device/browser/connect. The device token is encrypted at rest.

  • No web UI: everything a user or admin does is an MCP tool; server-wide settings are environment variables. Destructive actions are two-step (dry run → confirmation token).

  • Trust model: the operator can read everything on disk. Note content also passes through your Claude conversation. Both are inherent; read the data-policy note in the architecture before syncing anything sensitive.

Connecting Claude

Once deployed at https://mcp.example.com/mcp:

  • claude.ai / Claude Desktop / mobile: Settings → Connectors → Add custom connector → paste the URL and the client ID your operator gives you → sign in at your identity provider.

  • Claude Code:

    claude mcp add --transport http scriptorium https://mcp.example.com/mcp --client-id scriptorium-claude-code
    # then inside Claude Code:
    /mcp   # sign in

Deploying

A docker/compose.example.yml with the server and worker (plus optional keycloak and ink profiles) and a reverse-proxy layout is described in the architecture document. Requirements: a public HTTPS hostname, an OIDC issuer reachable by Claude, a local filesystem for /data (not a network or FUSE mount), and a master key kept outside /data. See docs/Architecture.md §12–13.

The image is ghcr.io/milkyengineer/scriptorium for linux/amd64 and linux/arm64, tagged X.Y.Z, X.Y, X and latest. The compose example uses 0.1, which picks up patch releases; before 1.0 a minor release may change configuration, so move to the next minor tag after reading the changelog. The major tag 1 follows the 1.0 release.

Releasing

  1. On a branch, set version in pyproject.toml and __version__ in src/scriptorium/__init__.py to X.Y.Z, run uv lock, and add a ## X.Y.Z — YYYY-MM-DD section to CHANGELOG.md. Merge to main.

  2. Tag the merge commit on main and push the tag: git tag -a vX.Y.Z -m "Scriptorium X.Y.Z", then git push origin vX.Y.Z.

  3. .github/workflows/release.yml checks that the tag is on main and matches the package version, runs the tests and the licence gate, smoke-tests the amd64 image, pushes both architectures to GHCR, and creates the GitHub release from the changelog section. A tag with a pre-release suffix (vX.Y.Z-rc.1) is published as a pre-release and does not move latest or the short tags.

Roadmap

  1. Spikes (S0–S6): remarkable-mcp as an AGPL-free library · native notebook upload and re-upload under the original UUID · issuer + Claude OAuth end to end · Paper Pro Move rendering · free-tier behaviour · SQLite on the target filesystem · what Claude clients render

  2. M1 safe archive, single user · M2 OCR modes & search · M3 push · M4 backup/restore · M5 multi-user & admin · M6 hardening and 1.0

Details and acceptance criteria: docs/Plan/.

Licensing

Scriptorium is released under the MIT License.

Dependency licences were checked so that the Docker image can be distributed under MIT:

  • Permissive, included: remarkable-mcp (MIT, used as a library via a fork that makes its AGPL extras optional), rmscene (MIT), mcp (MIT), resvg-py (MIT), pypdfium2 (BSD-3/Apache-2.0), WeasyPrint (BSD-3), markdown-it-py (MIT), httpx (BSD-3), cryptography (Apache-2.0/BSD-3), PyJWT (MIT). Keycloak (Apache-2.0) is an optional separate container.

  • Deliberately excluded from the image: PyMuPDF (AGPL-3.0 or commercial) and ebooklib (AGPL-3.0-or-later), both hard dependencies of upstream remarkable-mcp — replaced by resvg-py for SVG rasterising, pypdfium2 for PDF pages, and WeasyPrint for Markdown → PDF; EPUB is pass-through bytes. rmink (AGPL-3.0-or-later) — image-to-ink conversion is provided by an optional, separately licensed scriptorium-ink sidecar container (AGPL, source published) until a clean-room MIT implementation on rmscene replaces it. rmc is not used (it pins an incompatible rmscene).

  • CI runs a licence gate over the built image and fails on any GPL/AGPL Python package.

If you add a dependency, keep it MIT/BSD/Apache-compatible or put it behind the sidecar boundary.

Acknowledgements

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives Claude direct access to your reMarkable tablet's notebooks, enabling document search, PDF rendering, handwriting transcription, and diagram conversion, all locally without API keys.
      6
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and exploring handwritten reMarkable notebooks through a natural conversation with Claude Desktop, with full-text search, classification, and source citations.
      16
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read, search, and traverse your reMarkable tablet library, including handwritten notes via OCR, turning it into a second brain.
      17
      22
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with reMarkable tablets, allowing users to send PDFs and EPUBs, print from any application, list and read documents, and render handwritten pages as images. It provides MCP tools and skills for Claude to read and write to the tablet.
      -