Supernote

supernote-mcp

Ratta Supernote電子ペーパータブレット向けのMCPサーバーです。AI エージェントがローカル Wi-Fi ネットワーク経由で Supernote を見て操作できます。

• スケッチや手書きをしている最中に画面をライブで取得 — 「今描いたものは何ですか？」
• 保存したノートブックを閲覧して読む — 認識された手書き文字をテキストとして、またはページを画像として取得できます。
• ファイルをアップロードして、デバイス上で読んだり注釈を付けたりできます。
• デバイスからファイルをダウンロードできます — 注釈付き PDF、エクスポートしたノート、保存されているファイルを取得できます。

共同でプロンプトを作成することを目的としています。計画セッション中にタブレットで手書きし、内容をそのまま会話に取り込んだり、エージェントに以前保存したノートを読ませて内容を推論させたりできます。

すべてのツールは遅延実行されます — 呼び出されたときにのみデバイスにアクセスするため、ツールを一度も呼び出さないセッションではタブレットへのネットワークアクセスは発生しません。

重要

非公式のコミュニティ開発プロジェクトです。Ratta／Supernote との提携、認可、推奨は受けていません。「Supernote」と「Ratta」はそれぞれの所有者の商標であり、ここでは識別の目的でのみ使用しています。このプロジェクトは、ファームウェアの更新によって変更されたり動作しなくなったりする可能性のある、リバースエンジニアリングされた非公開の LAN インターフェース（画面ミラーリングおよび Browse & Access）に依存しています。MIT ライセンスに基づき現状のまま提供されます。ご自身の責任でご利用ください。

画面キャプチャと .note の解析には、supernote-typescript を使用しています。

前提条件

• 画面ミラーリングに対応した Supernote（Manta／Nomad／A5X／A6X クラスのデバイス）。
• タブレットとこのサーバーを実行するマシンが同じ Wi-Fi ネットワークに接続されており、VPN またはプロキシが有効になっていないこと。いずれも LAN ミラー接続を妨げます。
• npx でインストールする場合は Node.js ≥ 18。bunx の場合は Bun。スタンドアロンバイナリにはどちらも必要ありません。

ミラーリングを有効にして IP アドレスを確認する

1. Supernote でサイドバーを開き、画面ミラーリング（「キャスト」／「スクリーンキャスト」とも呼ばれます）をオンにします。
2. ポップアップに 192.168.1.42 のようなアドレスが表示されます。これがデバイスの IP アドレスです。ミラーリングはポート 8080（http://<ip>:8080/screencast.mjpeg）で提供されます。サーバーが :8080 を自動的に追加します。
3. エージェントがキャンバスのスナップショットを取得できるようにしておきたい間は、ミラーリングをオンのままにしてください。

SUPERNOTE_IP 環境変数で IP アドレスを一度設定するか、ツールの ip 引数で呼び出しごとに渡してください（明示的な引数が環境変数より優先されます）。

Browse & Access（ファイルツール用）

supernote_list_files（およびノートツール）は、画面ミラーリングとは別のデバイス機能であるBrowse & Accessを使用します。これはポート 8089で動作する、内蔵の Wi-Fi ファイルサーバーです。

1. Supernote で画面の上端から下にスワイプしてドロップダウンツールバーを開き、Browse & Accessをタップします。
2. ポップアップに http://192.168.1.42:8089 のようなアドレスが表示され、有効な間は開いたままになります。デバイスの IP アドレスはミラーリング時と同じです。ツールはポート 8089 を自動的に使用します。
3. エージェントにファイルを読み込ませたりアップロードさせたりしたい間は、ポップアップを開いたままにしてください。

Browse & Access と画面ミラーリングは独立した切り替え機能です。タスクに必要な機能（または両方）を有効にしてください。検出時には各ポートを確認するため、どちらか一方だけが有効でもデバイスを見つけられます。

IP アドレスの変更への対処

ミラーリングのアドレスは DHCP リースであり、セッションごとに変わることがあります。安定して使用する方法は 2 つあります。

• 固定する（推奨）： ルーターで DHCP 予約を設定し、タブレットに常に同じ IP アドレスが割り当てられるようにします。これにより SUPERNOTE_IP が古いアドレスになることはありません。
• 自動フォールバック： 設定済みのアドレスに到達できない場合、またはアドレスが設定されていない場合、サーバーはローカルネットワークをスキャンしてミラーリングを探し、見つけたデバイスを使用して、新しい IP アドレスをログに記録します。これにより SUPERNOTE_IP を更新できます。スキャンはフォールバック時のみ実行され（通常の高速処理経路では実行されません）、サブネット上のポート 8080 を調べてミラーリングの multipart ストリームを探します。LAN をスキャンするよりもすぐにエラーにしたい場合は、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 を再起動して、次のように試してみてください：「Supernote のスナップショットを撮って、何を描いたか教えて。」

macOS では、ダウンロードしたバイナリは署名されていないため、初回起動時に Gatekeeper にブロックされる場合があります。 右クリックして「開く」を一度選ぶか、xattr -d com.apple.quarantine /path/to/supernote-mcp-darwin-arm64 を実行してください。

ツール

すべてのツールは省略可能な ip（デバイスの IP。必要に応じて :port を指定。デフォルトでは SUPERNOTE_IP を使用し、設定されていない場合は LAN をスキャンします）を受け付けます。失敗した場合は、処理が停止せず、明確で対処可能なメッセージを返します。

ツール	必要な機能	入力	戻り値
supernote_snapshot	Screen Mirroring（8080）	ip?	ライブ画面を image/png で返します
supernote_list_files	Browse & Access（8089）	ip?、path?	名前、フォルダー?、サイズ、日付、および次に渡す path の一覧を返します
supernote_read_note	Browse & Access（8089）	ip?、path	ページごとに認識された手書き文字／テキストを返します（または、認識が実行されていないことを示します）
supernote_render_note	Browse & Access（8089）	ip?、path、pages?	ノートのページを image/png で返します（全ページ。ただし最大20ページ。あるいは指定した pages）
supernote_download_file	Browse & Access（8089）	ip?、path、out?	デバイスからローカルファイルシステムにファイルをダウンロードします
supernote_upload_file	Browse & Access（8089）	ip?、path、directory?、filename?	ローカルファイルをデバイスにアップロードします（デバイスに書き込む唯一のツールです）

失敗した場合は、よくある原因（IP の誤り、該当機能がオフ、ホストとデバイスが VPN を介さない同じ Wi-Fi ネットワークに接続されていない）を示し、処理が停止せず、すばやく（10秒で）タイムアウトします。

supernote_upload_file を除くすべてのツールは読み取り専用です。supernote_upload_file はデバイスにファイルを書き込みます（サーバーがアクセスできるローカルファイルを読み取り、Browse & Access 経由で POST します）。 supernote_download_file はデバイスからファイルを読み取り、ローカルに保存します。注釈付き PDF、エクスポートしたノート、またはタブレットに保存されているファイルを取得するために使用してください。

適切なツールの選び方

サーバーはこのルーティングを MCP の instructions としても提供するため、接続されたエージェントが適切なツールを自動で選択します。対応表は次のとおりです。

やりたいこと…	こんなふうに伝える	ツール
今画面に表示されているものを確認する	「今描いたものは何？」「画面を見て」	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 は実行、型チェック、ビルドにのみ使用します。エンドユーザーには不要です。このリポジトリには、Bun を再現性のある形で提供する任意の devbox 環境が含まれています。システムにインストールした 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 は、両方で使われる共通のアドレス解決と LAN スキャンのフォールバックを備え、src/discover.ts はサブネットをスキャンし（ミラーまたは Browse & Access エンドポイントをプローブしてデバイスを認識します）。src/server.ts は stdio トランスポートを介して McpServer にツールを登録します。

ライセンス

MIT