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 

... [View full README on GitHub](https://github.com/ridget/supernote-mcp#readme)