The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Supernote listing page.
An MCP server for the Ratta Supernote e-ink tablet. It lets an AI agent see and work with your Supernote over the local Wi-Fi network:
The idea is collaborative prompting: handwrite on the tablet during a planning session and pull it straight into the conversation, or have the agent read and reason over notes you saved earlier.
Every tool is lazy — it touches the device only when invoked, so a session that never calls one makes no network calls to the tablet.
[!IMPORTANT] Unofficial, community-built project — not affiliated with, authorised by, or endorsed by Ratta / Supernote. "Supernote" and "Ratta" are trademarks of their respective owner, used here only for identification. It relies on reverse-engineered, undocumented LAN interfaces (screen mirror + Browse & Access) that may change or break with firmware updates. Provided as-is under the MIT license — use at your own risk.
Built on supernote-typescript for screen
capture and .note parsing.
npx install path: Node.js ≥ 18. For bunx: Bun. The standalone
binary needs neither.192.168.1.42. That's the device IP. The mirror serves on
port 8080 (http://<ip>:8080/screencast.mjpeg); the server appends :8080 for you.Set the IP once via the SUPERNOTE_IP environment variable, or pass it per-call as the tool's
ip argument (an explicit argument wins over the env var).
supernote_list_files (and the note tools) use a separate device feature from screen mirroring:
Browse & Access, the built-in Wi-Fi file server on port 8089.
http://192.168.1.42:8089 and stays open while it's active. The
device IP is the same as for mirroring; the tools target port 8089 automatically.Browse & Access and Screen Mirroring are independent toggles — enable whichever the task needs (or both). Discovery probes each port, so the device can be found with only one of them on.
The mirror address is a DHCP lease and can change between sessions. Two ways to stay robust:
SUPERNOTE_IP never goes stale.SUPERNOTE_IP. The scan only runs as a fallback (never on the fast path) and probes
port 8080 across your subnet for the mirror's multipart stream. Disable it with
SUPERNOTE_DISCOVER=0 if you'd rather it fail fast than scan the LAN.Pick whichever distribution suits you — none require this repo to be checked out.
Restart Claude Code, then try: "Snapshot my Supernote and tell me what I drew."
On macOS the downloaded binary is unsigned; the first run may be blocked by Gatekeeper. Right-click → Open once, or run
xattr -d com.apple.quarantine /path/to/supernote-mcp-darwin-arm64.
All tools accept an optional ip (device IP, optionally :port; defaults to SUPERNOTE_IP, else a
LAN scan) and return a clear, actionable message on failure rather than hanging.
| Tool | Needs | Input | Returns |
|---|---|---|---|
supernote_snapshot | Screen Mirroring (8080) | ip? | the live screen as image/png |
supernote_list_files | Browse & Access (8089) | ip?, path? | a listing — name, folder?, size, date, and a path to pass on |
supernote_read_note | Browse & Access (8089) | ip?, path | a note's recognized handwriting/text per page (or a note that recognition hasn't run) |
supernote_render_note | Browse & Access (8089) | ip?, path, pages? | note pages as image/png (all pages, capped at 20, or the pages you pick) |
supernote_upload_file | Browse & Access (8089) | ip?, path, directory?, filename? | uploads a local file to the device (the only tool that writes to it) |
Failures point at the usual causes — wrong IP, the relevant feature turned off, or the host/device not sharing a VPN-free Wi-Fi network — and time out fast (10s) rather than hanging.
All tools except supernote_upload_file are read-only. supernote_upload_file writes a file to
the device (it reads a local file the server can access and POSTs it over Browse & Access).
The server also ships this routing as MCP instructions, so a connected agent picks the right tool
on its own. The map:
| You want… | Say something like | Tool |
|---|---|---|
| What's on the screen right now | "what did I just draw?", "look at my screen" | supernote_snapshot |
| To find a saved note | "what notes do I have?", "find my note about X" | supernote_list_files |
| To read a note's words | "read / summarise my meeting notes" | supernote_read_note |
| To see a note's pages | "show me that sketch", "look at page 2" | supernote_render_note |
| To put a file on the tablet | "send this PDF to my Supernote" | supernote_upload_file |
Saved-note flow: supernote_list_files → take the entry's path → supernote_read_note (text,
cheap — prefer for words) or supernote_render_note (images, for drawings or notes without
recognized text). supernote_snapshot is separate — it's the current screen, not a saved file.
Bun is used only to run, typecheck, and build — it is not required by end users. This repo ships an optional devbox environment that provides Bun reproducibly; you can equally use a system Bun install.
bun build --compile cross-compiles too, e.g.
bun build --compile --target=bun-linux-x64 src/server.ts --outfile dist/supernote-mcp-linux-x64.
src/capture.ts wraps fetchMirrorFrame(${ip}:8080), which parses the device's
multipart/x-mixed-replace stream, extracts a frame, and decodes it via
image-js. The frame is re-encoded to PNG (sidestepping
PNG-vs-JPEG part-encoding differences across firmwares) and returned as base64. src/browse.ts
is a client for the Browse & Access HTTP file server (port 8089): it lists directories (parsing the
listing page's embedded JSON) and downloads files. src/resolve.ts holds the shared address
resolution + LAN-scan fallback used by both, and src/discover.ts does the subnet scan (probing the
mirror or Browse & Access endpoint to recognise the device). src/server.ts registers the tools on
an McpServer over the stdio transport.