Supernote

supernote-mcp

适用于 Ratta Supernote 墨水屏平板的 MCP 服务。它让 AI Agent 可以通过本地 Wi-Fi 网络查看和操作你的 Supernote：

• 获取实时屏幕画面，同时你在平板上绘画或手写——“我刚才画了什么？”
• 浏览和阅读已保存的笔记本——将识别出的手写内容作为文本读取，或将页面作为图像查看。
• 上传文件到设备，供你阅读或批注。
• 从设备下载文件——获取带批注的 PDF、导出的笔记或任何已存储的文件。

其理念是协作式提示：在规划期间于平板上手写，并直接将内容导入对话；或者让 Agent 阅读并推理你之前保存的笔记。

每个工具都是按需执行的——只有调用时才会访问设备，因此，不调用工具的会话不会向平板发起网络请求。

重要

非官方社区项目——与 Ratta / Supernote 无关联，未经其授权或认可。“Supernote”和“Ratta”是其各自所有者的商标，此处仅用于标识。本项目依赖通过逆向工程得出的未公开局域网接口（屏幕镜像 + Browse & Access），这些接口可能随固件更新而变化或失效。本项目按 MIT 许可证“原样”提供——使用风险由你自行承担。

屏幕捕获和 .note 解析基于 supernote-typescript 构建。

前提条件

• 支持屏幕镜像的 Supernote（Manta / Nomad / A5X / A6X 系列设备）。
• 平板和运行此服务的机器必须连接到同一 Wi-Fi 网络，且不能启用 VPN 或代理——否则局域网镜像连接会失效。
• 使用 npx 安装：需要 Node.js ≥ 18。使用 bunx：需要 Bun。独立二进制文件则不需要这些依赖。

启用镜像并查找 IP

1. 在 Supernote 上打开侧边栏并启用屏幕镜像（又称“Cast”/“Screencast”）。
2. 弹出窗口会显示类似 192.168.1.42 的地址。这就是设备 IP。镜像服务运行在端口 8080（http://<ip>:8080/screencast.mjpeg）；服务会自动为你添加 :8080。
3. 需要 Agent 能够截取画布时，请保持镜像开启。

通过 SUPERNOTE_IP 环境变量设置一次 IP，或者在每次调用时将 IP 作为工具的 ip 参数传入（显式参数优先于环境变量）。

Browse & Access（用于文件工具）

supernote_list_files（以及笔记工具）使用的是与屏幕镜像不同的设备功能：Browse & Access，即内置的 Wi-Fi 文件服务，运行在端口 8089。

1. 在 Supernote 上，从屏幕顶部向下滑动以打开下拉工具栏，然后点按 Browse & Access。
2. 弹出窗口会显示类似 http://192.168.1.42:8089 的地址，并在功能启用期间保持打开。设备 IP 与镜像使用的 IP 相同；工具会自动访问端口 8089。
3. 需要 Agent 读取或上传文件时，请保持弹出窗口打开。

Browse & Access 和屏幕镜像是彼此独立的开关——根据任务需要启用其中一个或两个。设备发现功能会分别探测这两个端口，因此只要启用其中一个就能找到设备。

应对 IP 变化

镜像地址是 DHCP 租约，可能会在不同会话间变化。以下两种方法可提高稳定性：

• **固定 IP（推荐）：**在路由器上添加 DHCP 保留规则，让平板始终获取相同的 IP，这样 SUPERNOTE_IP 就不会过期。
• 自动回退：如果配置的地址无法访问，或者没有设置地址，服务会扫描本地网络以查找镜像，使用找到的设备，并记录新的 IP，方便你更新 SUPERNOTE_IP。扫描仅作为回退方案运行（快速路径不会扫描），并会在子网内探测端口 8080，以查找镜像的 multipart 流。如果你宁愿快速失败也不想扫描局域网，可通过 SUPERNOTE_DISCOVER=0 禁用扫描。

安装并注册到 Claude Code

选择适合你的分发方式——无需检出此仓库。

# 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

重启 Claude Code，然后试试：“Snapshot my Supernote and tell me what I drew.”

在 macOS 上，下载的二进制文件未签名；首次运行时可能会被 Gatekeeper 拦截。 右键点击 → 打开一次，或运行 xattr -d com.apple.quarantine /path/to/supernote-mcp-darwin-arm64。

工具

所有工具都接受可选的 ip（设备 IP，可附加 :port；默认使用 SUPERNOTE_IP，否则扫描 局域网），失败时会返回清晰且可执行的提示，而不是一直挂起。

工具	所需功能	输入	返回内容
supernote_snapshot	屏幕镜像（8080）	ip?	实时屏幕图像，格式为 image/png
supernote_list_files	浏览与访问（8089）	ip?、path?	文件列表——名称、文件夹?、大小、日期，以及可传入后续工具的 path
supernote_read_note	浏览与访问（8089）	ip?、path	笔记中每页识别出的手写内容/文本（或者提示尚未进行识别）
supernote_render_note	浏览与访问（8089）	ip?、path、pages?	笔记页面图像，格式为 image/png（所有页面，最多 20 页，或你指定的 pages）
supernote_download_file	浏览与访问（8089）	ip?、path、out?	将设备中的文件下载到本地文件系统
supernote_upload_file	浏览与访问（8089）	ip?、path、directory?、filename?	将本地文件上传到设备（这是唯一会向设备写入内容的工具）

失败时会指出常见原因——IP 错误、相关功能已关闭，或主机与设备未连接到无需 VPN 的同一 Wi-Fi 网络——并会在短时间内（10 秒）超时，而不会一直挂起。

除 supernote_upload_file 外，所有工具都为只读。supernote_upload_file 会向设备写入文件（读取服务可访问的本地文件，然后通过“浏览与访问”功能 POST 上传）。 supernote_download_file 会读取设备中的文件并保存到本地——可用它取回批注 PDF、导出的笔记或平板电脑上存储的任何文件。

选择合适的工具

服务器也会通过 MCP instructions 提供这套路由说明，因此已连接的 Agent 会自行选择合适的工具。对应关系如下：

你的需求……	可以这样说	工具
查看屏幕上的当前内容	“我刚才画了什么？”、“看看我的屏幕”	supernote_snapshot
查找已保存的笔记	“我有哪些笔记？”、“找找我写的关于 X 的笔记”	supernote_list_files
阅读笔记内容	“阅读 / 总结我的会议笔记”	supernote_read_note
查看笔记页面	“给我看看那张草图”、“看看第 2 页”	supernote_render_note
将文件放到平板电脑上	“把这个 PDF 发到我的 Supernote”	supernote_upload_file
从平板电脑取出文件	“下载我加了批注的 PDF”	supernote_download_file

已保存笔记的流程： supernote_list_files → 获取条目的 path → 使用 supernote_read_note（文本，开销较低——读取文字时优先使用）或 supernote_render_note（图像，适用于绘图或没有识别文本的笔记）。supernote_snapshot 则不同——它获取的是当前屏幕，而不是已保存的文件。

下载流程： supernote_list_files → 找到文件 → 使用条目的 path 调用 supernote_download_file → 文件保存到本地，以便进行处理（例如渲染加了批注的 PDF 页面）。

本地开发

Bun 仅用于运行、类型检查和构建——终端用户无需安装它。此仓库提供可选的 devbox 环境，可确保一致地使用 Bun；你也可以使用系统中已安装的 Bun。

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 也支持交叉编译，例如： bun build --compile --target=bun-linux-x64 src/server.ts --outfile dist/supernote-mcp-linux-x64。

工作原理

src/capture.ts 会包装 fetchMirrorFrame(${ip}:8080)，解析设备的 multipart/x-mixed-replace 流，提取一帧，并通过 image-js 解码。随后将这一帧重新编码为 PNG（避开不同固件之间 PNG 与 JPEG 部分编码的差异），并以 base64 格式返回。src/browse.ts 是 Browse & Access HTTP 文件服务（端口 8089）的客户端：它会列出目录（解析目录列表页面中嵌入的 JSON）并下载文件。src/resolve.ts 存放两者共用的地址解析与局域网扫描回退逻辑，而 src/discover.ts 执行子网扫描（探测 mirror 或 Browse & Access 端点以识别设备）。src/server.ts 通过 stdio 传输在 McpServer 上注册工具。

许可证

MIT