{
  "markdown": "# supernote-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server for the [Ratta Supernote](https://supernote.com)\ne-ink tablet. It lets an AI agent **see and work with your Supernote over the local Wi-Fi network**:\n\n- **Grab the live screen** while you sketch or handwrite — *\"what did I just draw?\"*\n- **Browse and read your saved notebooks** — recognized handwriting as **text**, or pages as **images**.\n- **Upload files** to the device for you to read or annotate.\n\nThe idea is collaborative prompting: handwrite on the tablet during a planning session and pull it\nstraight into the conversation, or have the agent read and reason over notes you saved earlier.\n\nEvery tool is **lazy** — it touches the device only when invoked, so a session that never calls one\nmakes no network calls to the tablet.\n\n> [!IMPORTANT]\n> **Unofficial, community-built project — not affiliated with, authorised by, or endorsed by\n> Ratta / Supernote.** \"Supernote\" and \"Ratta\" are trademarks of their respective owner, used here\n> only for identification. It relies on **reverse-engineered, undocumented LAN interfaces** (screen\n> mirror + Browse & Access) that may change or break with firmware updates. Provided **as-is** under\n> the MIT license — use at your own risk.\n\nBuilt on [`supernote-typescript`](https://github.com/philips/supernote-typescript) for screen\ncapture and `.note` parsing.\n\n## Prerequisites\n\n- A Supernote that supports **Screen Mirroring** (Manta / Nomad / A5X / A6X-class devices).\n- The tablet and the machine running this server on the **same Wi-Fi network**, with\n  **no VPN or proxy** active — either will break the LAN mirror connection.\n- For the `npx` install path: **Node.js ≥ 18**. For `bunx`: [Bun](https://bun.sh). The standalone\n  binary needs neither.\n\n## Enable mirroring and find the IP\n\n1. On the Supernote, open the sidebar and turn on **Screen Mirroring** (a.k.a. \"Cast\"/\"Screencast\").\n2. A popup shows an address like `192.168.1.42`. That's the device IP. The mirror serves on\n   **port 8080** (`http://<ip>:8080/screencast.mjpeg`); the server appends `:8080` for you.\n3. Keep mirroring on while you want the agent to be able to snapshot the canvas.\n\nSet the IP once via the `SUPERNOTE_IP` environment variable, or pass it per-call as the tool's\n`ip` argument (an explicit argument wins over the env var).\n\n### Browse & Access (for the file tools)\n\n`supernote_list_files` (and the note tools) use a **separate** device feature from screen mirroring:\n**Browse & Access**, the built-in Wi-Fi file server on **port 8089**.\n\n1. On the Supernote, **swipe down from the top** of the screen to open the drop-down toolbar and tap\n   **Browse & Access**.\n2. A popup shows an address like `http://192.168.1.42:8089` and stays open while it's active. The\n   device IP is the same as for mirroring; the tools target port 8089 automatically.\n3. Keep the popup open while you want the agent to read or upload files.\n\nBrowse & Access and Screen Mirroring are independent toggles — enable whichever the task needs (or\nboth). Discovery probes each port, so the device can be found with only one of them on.\n\n### Coping with a changing IP\n\nThe mirror address is a DHCP lease and can change between sessions. Two ways to stay robust:\n\n- **Pin it (recommended):** add a DHCP reservation on your router so the tablet always gets the\n  same IP, then `SUPERNOTE_IP` never goes stale.\n- **Automatic fallback:** if the configured address is unreachable — or none is set — the server\n  **scans the local network** for the mirror, uses the device it finds, and logs the new IP so you\n  can update `SUPERNOTE_IP`. The scan only runs as a fallback (never on the fast path) and probes\n  port 8080 across your subnet for the mirror's `multipart` stream. Disable it with\n  `SUPERNOTE_DISCOVER=0` if you'd rather it fail fast than scan the LAN.\n\n## Install & register with Claude Code\n\nPick whichever distribution suits you — none require this repo to be checked out.\n\n```bash\n# Recommended: published npm package via Node's npx\nclaude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- npx -y supernote-mcp\n\n# If you already have Bun\nclaude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- bunx supernote-mcp\n\n# Standalone binary (no runtime needed) — download the asset for your platform from the\n# latest GitHub Release (supernote-mcp-darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64,\n# -windows-x64.exe), make it executable, then register its path:\nchmod +x ./supernote-mcp-darwin-arm64\nclaude mcp add supernote --scope user --env SUPERNOTE_IP=192.168.1.42 -- /path/to/supernote-mcp-darwin-arm64\n```\n\nRestart Claude Code, then try: *\"Snapshot my Supernote and tell me what I drew.\"*\n\n> On macOS the downloaded binary is unsigned; the first run may be blocked by Gatekeeper.\n> Right-click → Open once, or run `xattr -d com.apple.quarantine /path/to/supernote-mcp-darwin-arm64`.\n\n## The tools\n\nAll tools accept an optional `ip` (device IP, optionally `:port`; defaults to `SUPERNOTE_IP`, else a\nLAN scan) and return a clear, actionable message on failure rather than hanging.\n\n| Tool | Needs | Input | Returns |\n|------|-------|-------|---------|\n| `supernote_snapshot` | Screen Mirroring (8080) | `ip?` | the live screen as `image/png` |\n| `supernote_list_files` | Browse & Access (8089) | `ip?`, `path?` | a listing — name, folder?, size, date, and a `path` to pass on |\n| `supernote_read_note` | Browse & Access (8089) | `ip?`, `path` | a note's recognized handwriting/text per page (or a note that recognition hasn't run) |\n| `supernote_render_note` | Browse & Access (8089) | `ip?`, `path`, `pages?` | note pages as `image/png` (all pages, capped at 20, or the `pages` you pick) |\n| `supernote_upload_file` | Browse & Access (8089) | `ip?`, `path`, `directory?`, `filename?` | uploads a **local** file to the device (the only tool that **writes** to it) |\n\nFailures point at the usual causes — wrong IP, the relevant feature turned off, or the host/device\nnot sharing a VPN-free Wi-Fi network — and time out fast (10s) rather than hanging.\n\nAll tools except `supernote_upload_file` are read-only. `supernote_upload_file` **writes** a file to\nthe device (it reads a local file the server can access and POSTs it over Browse & Access).\n\n### Choosing the right tool\n\nThe server also ships this routing as MCP `instructions`, so a connected agent picks the right tool\non its own. The map:\n\n| You want… | Say something like | Tool |\n|-----------|--------------------|------|\n| What's on the screen *right now* | \"what did I just draw?\", \"look at my screen\" | `supernote_snapshot` |\n| To find a saved note | \"what notes do I have?\", \"find my note about X\" | `supernote_list_files` |\n| To read a note's words | \"read / summarise my meeting notes\" | `supernote_read_note` |\n| To see a note's pages | \"show me that sketch\", \"look at page 2\" | `supernote_render_note` |\n| To put a file on the tablet | \"send this PDF to my Supernote\" | `supernote_upload_file` |\n\n**Saved-note flow:** `supernote_list_files` → take the entry's `path` → `supernote_read_note` (text,\ncheap — prefer for words) or `supernote_render_note` (images, for drawings or notes without\nrecognized text). `supernote_snapshot` is separate — it's the *current screen*, not a saved file.\n\n## Local development\n\nBun is used only to run, typecheck, and build — it is **not** required by end users. This repo ships\nan optional [devbox](https://www.jetify.com/devbox) environment that provides Bun reproducibly; you\ncan equally use a system Bun install.\n\n```bash\nbun install\n\n# Capture-first verification against a real device (writes a PNG you can open):\nbun run src/capture.ts --ip 192.168.1.42 --out frame.png\n\n# Browse & Access (port 8089) — list a directory, download a file, upload a file:\nbun run src/browse.ts list --ip 192.168.1.42 --path /Note\nbun run src/browse.ts get  --ip 192.168.1.42 --path /Note/obsidian/x.note --out x.note\nbun run src/browse.ts put  --ip 192.168.1.42 --path ./doc.pdf --dir /INBOX\n\n# Run the MCP server over stdio:\nbun run src/server.ts\n\n# Inspect the tool interactively:\nbunx @modelcontextprotocol/inspector bun run src/server.ts\n\nbun run test           # unit tests (bun:test)\nbun run typecheck      # tsc --noEmit\nbun run build          # node-compatible bundle -> dist/server.js (the npx/bunx entry)\nbun run build:binary   # self-contained executable -> dist/supernote-mcp\n```\n\n`bun build --compile` cross-compiles too, e.g.\n`bun build --compile --target=bun-linux-x64 src/server.ts --outfile dist/supernote-mcp-linux-x64`.\n\n## How it works\n\n`src/capture.ts` wraps `fetchMirrorFrame(`${ip}:8080`)`, which parses the device's\n`multipart/x-mixed-replace` stream, extracts a frame, and decodes it via\n[`image-js`](https://github.com/image-js/image-js). The frame is re-encoded to PNG (sidestepping\nPNG-vs-JPEG part-encoding differences across firmwares) and returned as base64. `src/browse.ts`\nis a client for the Browse & Access HTTP file server (port 8089): it lists directories (parsing the\nlisting page's embedded JSON) and downloads files. `src/resolve.ts` holds the shared address\nresolution + LAN-scan fallback used by both, and `src/discover.ts` does the subnet scan (probing the\nmirror or Browse & Access endpoint to recognise the device). `src/server.ts` registers the tools on\nan `McpServer` over the stdio transport.\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 9383,
  "sha": "844bb019bba4f7d166ce016d9ee59b67250e7de2a213c74665a428f41b497365",
  "repo_slug": "ridget/supernote-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ridget_supernote_mcp_6a476aca/readme"
}