supernote-mcp

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:

• Grab the live screen while you sketch or handwrite — "what did I just draw?"
• Browse and read your saved notebooks — recognized handwriting as text, or pages as images.
• Upload files to the device for you to read or annotate.

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.

Prerequisites

• A Supernote that supports Screen Mirroring (Manta / Nomad / A5X / A6X-class devices).
• The tablet and the machine running this server on the same Wi-Fi network, with no VPN or proxy active — either will break the LAN mirror connection.
• For the npx install path: Node.js ≥ 18. For bunx: Bun. The standalone binary needs neither.

Enable mirroring and find the IP

1. On the Supernote, open the sidebar and turn on Screen Mirroring (a.k.a. "Cast"/"Screencast").
2. A popup shows an address like 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.
3. Keep mirroring on while you want the agent to be able to snapshot the canvas.

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).

Browse & Access (for the file tools)

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.

1. On the Supernote, swipe down from the top of the screen to open the drop-down toolbar and tap Browse & Access.
2. A popup shows an address like 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.
3. Keep the popup open while you want the agent to read or upload files.

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.

Coping with a changing IP

The mirror address is a DHCP lease and can change between sessions. Two ways to stay robust:

• Pin it (recommended): add a DHCP reservation on your router so the tablet always gets the same IP, then SUPERNOTE_IP never goes stale.
• Automatic fallback: if the configured address is unreachable — or none is set — the server scans the local network for the mirror, uses the device it finds, and logs the new IP so you can update 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.

Install & register with Claude Code

Pick whichever distribution suits you — none require this repo to be checked out.

# Recommended: published npm package via Node's npx
claude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- npx -y supernote-mcp

# If you already have Bun
claude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- bunx supernote-mcp

# Standalone binary (no runtime needed) — download the asset for your platform from the
# latest GitHub Release (supernote-mcp-darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64,
# -windows-x64.exe), make it executable, then register its path:
chmod +x ./supernote-mcp-darwin-arm64
claude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- /path/to/supernote-mcp-darwin-arm64

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.

The tools

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.

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).

Choosing the right tool

The server also ships this routing as MCP instructions, so a connected agent picks the right tool on its own. The map:

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.

Local development

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 install

# Capture-first verification against a real device (writes a PNG you can open):
bun run src/capture.ts --ip 192.168.1.42 --out frame.png

# Browse & Access (port 8089) — list a directory, download a file, upload a file:
bun run src/browse.ts list --ip 192.168.1.42 --path /Note
bun run src/browse.ts get  --ip 192.168.1.42 --path /Note/obsidian/x.note --out x.note
bun run src/browse.ts put  --ip 192.168.1.42 --path ./doc.pdf --dir /INBOX

# Run the MCP server over stdio:
bun run src/server.ts

# Inspect the tool interactively:
bunx @modelcontextprotocol/inspector bun run src/server.ts

bun run test           # unit tests (bun:test)
bun run typecheck      # tsc --noEmit
bun run build          # node-compatible bundle -> dist/server.js (the npx/bunx entry)
bun run build:binary   # self-contained executable -> dist/supernote-mcp

bun build --compile cross-compiles too, e.g. bun build --compile --target=bun-linux-x64 src/server.ts --outfile dist/supernote-mcp-linux-x64.

How it works

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.

License

MIT