Lets an AI agent capture the screen, read handwritten notes, and manage files on a Ratta Supernote e-ink tablet over local Wi-Fi.
Also known as ridget/supernote-mcp, supernote-mcp
- Stars
- 2
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- 0.2.2
- Last commit
- Sep 22, 2026
- License
- MIT
What is Supernote MCP?
Supernote lets an AI agent capture the screen, read handwritten notes, and manage files on a Ratta Supernote e-ink tablet over local Wi-Fi. It exposes 6 tools, such as supernote_snapshot, supernote_list_files, supernote_read_note.
Summary generated from the project's README
About Supernote MCP server
Supernote provides a way for AI agents to interact with Ratta Supernote e-ink tablets over a local Wi-Fi network. This server allows an agent to view live screen captures of your sketches or handwriting and manage files stored on the device. It is designed for developers and users who want to combine handwritten planning with AI reasoning by pulling notes directly into a conversation.
To use this server, the tablet and the host machine must be on the same Wi-Fi network without a VPN or proxy. You must enable Screen Mirroring on port 8080 for snapshots or Browse & Access on port 8089 for file management. The server can be installed via npx, bunx, or as a standalone binary. It uses the SUPERNOTE_IP environment variable to locate the device, though it can also perform a local network scan to find the tablet automatically.
Specific tools include supernote_snapshot for capturing the current canvas, supernote_read_note for extracting recognized handwriting as text, and supernote_render_note for viewing pages as images. You can also use supernote_upload_file to send documents to the tablet or supernote_download_file to retrieve annotated PDFs and exported notes.
What you can do with it
- 1Analyze live sketchesAsk the AI to describe or interpret what you are currently drawing on your tablet screen.
- 2Transfer documents to tabletSend a local PDF file directly to your Supernote for reading or annotation.
- 3Retrieve annotated filesDownload a PDF from your device that you have already marked up with handwritten notes.
Written from the project's README. Every use case is checked against a quote from it.
How to install Supernote MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Supernote MCP in Claude Code
$ claude mcp add supernote-mcp -- npx -y supernote-mcpInstall Supernote MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"supernote-mcp": {
"command": "npx",
"args": [
"-y",
"supernote-mcp"
]
}
}
}Install Supernote MCP in VS Code
.vscode/mcp.json
{
"servers": {
"supernote-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"supernote-mcp"
]
}
}
}Install Supernote MCP in VS Code CLI
$ code --add-mcp '{"name":"supernote-mcp","type":"stdio","command":"npx","args":["-y","supernote-mcp"]}'Install Supernote MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"supernote-mcp": {
"command": "npx",
"args": [
"-y",
"supernote-mcp"
]
}
}
}Install Supernote MCP in Codex
$ codex mcp add supernote-mcp -- npx -y supernote-mcpInstall Supernote MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.supernote-mcp] command = "npx" args = ["-y", "supernote-mcp"]
Install Supernote MCP in Gemini CLI
$ gemini mcp add -s user supernote-mcp npx -- -y supernote-mcpInstall Supernote MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"supernote-mcp": {
"command": "npx",
"args": [
"-y",
"supernote-mcp"
]
}
}
}Supernote MCP tools 6
Detected from the READMEsupernote_snapshotsupernote_list_filessupernote_read_notesupernote_render_notesupernote_download_filesupernote_upload_file
| supernote_snapshot | — | |
| supernote_list_files | — | |
| supernote_read_note | — | |
| supernote_render_note | — | |
| supernote_download_file | — | |
| supernote_upload_file | — |
Configuration
SUPERNOTE_DISCOVERSet to 0 to disable the LAN-scan fallback used when SUPERNOTE_IP is unset or unreachable.
SUPERNOTE_IPDevice IP (optionally with :port) from the Supernote mirroring popup. Optional — if unset, the server scans the LAN for the mirror.
| Name | Description | |
|---|---|---|
| SUPERNOTE_DISCOVER | Set to 0 to disable the LAN-scan fallback used when SUPERNOTE_IP is unset or unreachable. | |
| SUPERNOTE_IP | Device IP (optionally with :port) from the Supernote mirroring popup. Optional — if unset, the server scans the LAN for the mirror. |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableridget/supernote-mcp is public and reachablegithub.com/ridget/supernote-mcp ↗Pass
- Package names this repository as its sourcesupernote-mcp names ridget/supernote-mcp as sourcenpmjs.com/package/supernote-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-22github.com/ridget/supernote-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from supernote-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsupernote-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.
- Download files from the device — retrieve annotated PDFs, exported notes, or any stored file.
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
npxinstall path: Node.js ≥ 18. Forbunx: Bun. The standalone binary needs neither.
Enable mirroring and find the IP
- On the Supernote, open the sidebar and turn on Screen Mirroring (a.k.a. "Cast"/"Screencast").
- 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:8080for you. - 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.
- On the Supernote, swipe down from the top of the screen to open the drop-down toolbar and tap Browse & Access.
- A popup shows an address like
http://192.168.1.42:8089and stays open while it's active. The device IP is the same as for mirroring; the tools target port 8089 automatically. - 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_IPnever 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'smultipartstream. Disable it withSUPERNOTE_DISCOVER=0if 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.
| 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_download_file |
Browse & Access (8089) | ip?, path, out? |
downloads a file from the device to the local filesystem |
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).
supernote_download_file reads a file from the device and saves it locally — use it to retrieve
annotated PDFs, exported notes, or any file stored on the tablet.
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:
| 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 |
| To get a file off the tablet | "download my annotated PDF" | supernote_download_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.
Download flow: supernote_list_files → find the file → supernote_download_file with the
entry's path → file is saved locally for processing (e.g. rendering an annotated PDF's pages).
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
Supernote MCP questions
How do I add Supernote MCP to Claude Code?
Run claude mcp add supernote-mcp -- npx -y supernote-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Supernote MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Supernote MCP provide?
It exposes 6 tools, including supernote_snapshot, supernote_list_files, supernote_read_note, supernote_render_note, supernote_download_file.
What hardware is required to use this server?
You need a Supernote device that supports Screen Mirroring, such as Manta, Nomad, A5X, or A6X-class devices.
How do I handle the tablet's IP address changing?
You can pin the IP using a DHCP reservation on your router, or the server can automatically scan the local network for the device if the configured address is unreachable.
Is this an official product from Supernote?
No, this is an unofficial, community-built project and is not affiliated with or endorsed by Ratta or Supernote.