Onsense

onsense — PC の AI エージェント向けスマートフォンのカメラ、センサー、ファイル

説明するのではなく、AI に見せましょう。 onsense は、onSense Android アプリ用の PC 側 MCP ブローカーです。PC で uvx onsense pair を実行すると、Claude Code、Claude Desktop、Codex、自作のエージェントなど、MCP 対応のあらゆる AI がスマートフォンのカメラ映像を見たり、センサーの読み取り値を取得したり、ファイルやクリップボードの内容を双方向にやり取りしたりできるようになります。クラウド経由の中継なし。ADB なし。

PC 上で動作する Claude Code が、スマートフォンのセンサーを読み取り、カメラ映像を確認して、ローカル Wi-Fi 経由でリアルタイムに質問へ回答します。

…Codex でも同じように使えます。onSense は標準的な MCP サーバーなので、あらゆる MCP クライアントで動作します。

---

アーキテクチャ

Android phone (onSense app)           PC (this package)           AI client
  HTTP provider :8080        ←→    stdio MCP broker          Claude / Codex / …
  camera frames, photos,           onsense serve               natural-language or
  sensors, QR pairing              onsense clip :8770          /onsense tool calls

• スマートフォンはポート 8080 で HTTP プロバイダーを実行します。ペアリングトークンで保護されたカメラのフレーム、最近の写真、センサーの読み取り値を提供します。
• PC パッケージ（onsense）は stdio MCP ブローカーです。AI クライアントからの MCP ツール呼び出しを、スマートフォンへの HTTP リクエストに変換します。
• デバイスの検出には mDNS（_onsense._tcp.local.）を使用します。スマートフォンの IP アドレスが変わると、ブローカーが自動的に再検出するため、手動で再設定する必要はありません。
• オプションのポート 8770 で動作するクリップブリッジデーモンを使うと、スマートフォンから PC にカメラのフレーム、ファイル、クリップボードの内容を送信できます（有効にした場合は、スマートフォンから PC のクリップボードの内容を取得することもできます）。

---

必要条件

• uv（uvx を提供します。管理対象の Python を自動でダウンロードするため、Python を別途インストールする必要はありません）
• onSense Android アプリがインストールされ、PC と同じローカル Wi-Fi ネットワークに接続されているスマートフォン
• Claude Code、Codex、または stdio MCP クライアントなどの MCP 対応 AI クライアント

---

クイックスタート

0. uv がインストールされていない新しい PC の場合：アプリのセットアップヘルパーを使う（推奨）

初期状態の PC には uvx がないため、以下のコマンドを実行すると 「'uvx' は認識されていません」 というエラーが発生します。最も簡単な解決方法は、まず onSense アプリをインストールし、**「Start PC setup helper」**をタップして、表示されたアドレスを PC で開くことです。uv のインストール、ペアリング、MCP サーバーの登録をまとめて実行する 1 行のコマンドが表示されます。また、PC からスマートフォンへ接続するため、Windows ファイアウォールも回避できます。

uv を自分でインストールする場合は、次の 1 行を実行します。

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"   # make uvx visible in this same shell

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

1. スマートフォンをペアリングする

この操作を一度だけ実行します。PC に QR コードが表示されるので、onSense アプリの「Scan PC QR」からスキャンしてください。スマートフォンから PC にアドレスとトークンが送信され、MCP サーバーが自動的に登録されます。

uvx onsense pair

ペアリング後、新しい onsense MCP サーバーを認識させるため、AI クライアントを一度再起動してください。

2. 使用する

AI クライアントに自然な言葉で依頼します。

「スマートフォンの前にあるものを撮影して。」 「現在のセンサーの読み取り値を教えて。」 「スマートフォンにある最近の写真を 5 枚見せて。」

MCP ツールが自動的に呼び出されます。Claude Code では、ペアリング時にインストールされる組み込みの /onsense スラッシュコマンドも使用できます。

3. 問題を診断する

uvx onsense doctor           # checks Python, uv, MCP, Claude registration, mDNS, phone reachability
uvx onsense doctor --base http://192.168.1.5:8080 --token YOUR_PAIRING_TOKEN

Windows：QRコードのスキャンがタイムアウトする場合

最も多い原因は、Windows ファイアウォールがスマートフォンからの受信接続を遮断していることです。

• Wi-Fi ネットワークのプロファイルが パブリック の場合、受信トラフィックは厳しくブロックされます。プライベート に切り替える（設定 → ネットワーク → 使用中の Wi-Fi → ネットワーク プロファイル）か、受信ポートが一切不要なアプリの PC セットアップヘルパー を使用してください。

• プライベートネットワークでは、管理者として実行し、永続的な許可ルールを一度追加してください。

  uvx onsense pair --fix-firewall
  

  初回起動時のファイアウォールポップアップは プログラムのパスに紐づいて おり、uvx の一時パスによって無効になるため、上記のポート単位のルール（TCP 8765～8774、プライベート）が実際に有効な設定です。

• ポート 8765 が使用中の場合、pair は自動的に次の空きポート（最大 8774）に切り替え、QRコードにも実際のポートが反映されます。操作は不要です。

---

サブコマンド

コマンド	機能
uvx onsense pair	PC に QRコードを表示します。スマートフォンでスキャンすると {base, token} が送信され、MCP が自動登録されます
uvx onsense pair "onsense://pair?base=...&token=..."	ペアリング URI を直接解析します（スマートフォンに表示された QRコードから手動でコピー）
uvx onsense pair --img screenshot.png	スクリーンショットファイルからペアリング QRコードを読み取ります（opencv が必要です）
uvx onsense serve	MCP サーバーを実行します（stdio）。--no-clip を指定しない場合は、クリップデーモンも自動的に起動します
uvx onsense serve --no-clip	クリップデーモンを起動せずに、MCP サーバーのみを実行します
uvx onsense clip	クリップブリッジデーモンを単独で実行します（ポート 8770）
uvx onsense clip --allow-pull	スマートフォンからのプルを有効にします。スマートフォンから GET /clip を実行して PC のクリップボードを取得できます
uvx onsense clip --set-clipboard	受信した内容を PC の OS クリップボードに自動挿入します（デフォルトでは無効）
uvx onsense pair --fix-firewall	（Windows、管理者権限が必要）永続的なポート単位のファイアウォールルールを追加し、通常どおりペアリングします
uvx onsense doctor	インストール、接続状況、スマートフォンからの到達性を診断します
uvx onsense stats	ローカルのみのアクティベーション統計を表示します（--json、--reset）。自動アップロードは行われません

---

その他の MCP クライアント（Claude Desktop、Codex など）

uvx onsense pair は Claude Code にサーバーを自動登録します（claude mcp add を使用）。この1行での自動セットアップは Claude Code 固有です。MCP サーバー自体は標準の stdio MCP なので、手動で追加すれば MCP 対応のクライアントであればどれでも動作します。まず uvx onsense pair を一度実行してください。スマートフォンのアドレスとトークンが ~/.onsense/pair.json に保存され、サーバーはリクエスト時にそのファイルを読み取ります。そのため、各クライアントの設定にトークンを記述する必要はなく、mDNS によってスマートフォンの IP が自動的に追跡されます。

Claude Desktop — claude_desktop_config.json に追加します。

{ "mcpServers": { "onsense": { "command": "uvx", "args": ["onsense", "serve"] } } }

Codex — CLI から登録します（Codex CLI 0.142.5 で確認済み）。

codex mcp add onsense -- uvx onsense serve

Codex のサンドボックスに関する注意： Codex のデフォルトのサンドボックスではネットワークアクセスがブロックされるため、MCP サーバーはスマートフォンに接続できず、ツール呼び出しはエラーを表示せずに失敗します。onsense が LAN 上のスマートフォンと通信できるよう、ネットワークアクセスを有効にして Codex を実行してください（例：--sandbox danger-full-access を指定するか、ネットワークを許可するサンドボックスポリシーを設定します）。

または、~/.codex/config.toml に追加します。

[mcp_servers.onsense]
command = "uvx"
args = ["onsense", "serve"]

サーバーを追加した後、クライアントを一度再起動してください。その他の stdio MCP クライアントも同様に動作します。uvx onsense serve を指定してください。

---

MCP ツール

ペアリングすると、これらのツールが AI クライアントに公開されます。

ツール	説明
get_live_frame()	スマートフォンの現在のカメラフレームを撮影します（JPEG 画像を返します）
read_sensors()	スマートフォンのセンサー値を JSON 形式で返します：バッテリー残量／充電状態、周囲光（ルクス）、加速度計（x/y/z）
recent_photos(limit=10)	スマートフォン内の最近の写真を一覧表示します：id、name、date_added、size、width、height
get_photo(id, max_width=1024, save_original=False)	id を指定して写真を取得します（max_width に合わせて縮小されます）。id は recent_photos から指定してください。get_reference と同じ Downloads フォルダーにも保存され、パスが返されるため、画像は会話の終了後も保持されます。save_original=True にすると、縮小版ではなくフル解像度の画像を保存します
rename_photo(path, name)	取得したファイルの名前を、画像に実際に写っている内容を表すものに変更します（photo_1000024531.jpg → whiteboard_sprint_plan.jpg）。AI が画像を確認した直後に呼び出すため、追加のトークンは消費しません
get_reference()	スマートフォンで参照ソースとして指定されているもの（ライブカメラフレーム、撮影した写真、任意のファイル（画像以外も含む））を取得し、パスとメタデータを付けてディスクに保存します。ファイルと撮影データを橋渡しする中核機能です
get_cam_fps()	スマートフォンの現在のカメラ FPS 設定を読み取ります（15 = 高パフォーマンス、2 = バランス、0 = オンデマンド）
set_cam_fps(fps)	スマートフォンのカメラ FPS を設定します：15（高パフォーマンス）、2（バランス、推奨）、0（省電力／オンデマンド）

スマートフォンの IP が変わった場合、ブローカーはエラーを通知する前に mDNS 自動検出を使って再試行します。

---

Clip Bridge（スマートフォン ↔ PC のファイルとクリップボード）

onsense serve は、ポート 8770 でクリップデーモンを自動的に起動します。onsense clip で単独実行することもできます。

スマートフォン → PC への送信（POST /clip）

onSense Android アプリから PC にコンテンツを送信できます。

• 画像は ONSENSE_CLIP_DIR（デフォルトは <tempdir>/onsense/）内の latest.jpg としてディスクに保存されます。
• テキストファイルはディスクに保存されます。
• その他のファイル（動画、PDF など）は、ファイル名を維持してディスクに保存されます。
• --set-clipboard が有効な場合、画像とテキストは PC の OS クリップボードにも取り込まれるため、すぐに Ctrl+V で貼り付けられます。

デフォルトでは --set-clipboard はオフです。ファイルはディスクに保存されますが、クリップボードには触れません。

PC → スマートフォンからの取得（GET /clip）

デフォルトでは無効です。次のコマンドで有効にします。

uvx onsense clip --allow-pull

有効にすると、スマートフォンから GET /clip で現在の PC のクリップボードの内容を取得できます（コピーされたファイル、画像、テキストの順に返されます）。クリップボードが空の場合は 204 を返します。

ポートと環境変数

変数	デフォルト	用途
PHONE_BASE	（ペアリング時の値）	スマートフォンの HTTP ベース URL。例：http://192.168.1.5:8080
PHONE_TOKEN	（ペアリング時の値）	ペアリング認証トークン
ONSENSE_CLIP_DIR	<tempdir>/onsense	送信されたファイルの保存先ディレクトリ
ONSENSE_CLIP_MAX_MB	200	受信ファイルの最大サイズ（MB、0 = 無制限）
ONSENSE_CLIP_ALLOW_PULL	0	CLI フラグを使わずに PC→スマートフォンへの取得を有効にするには 1 を設定します
ONSENSE_CLIP_SET_CLIPBOARD	0	CLI フラグを使わずに OS クリップボードへの自動取り込みを有効にするには 1 を設定します
ONSENSE_TEST_FRAME	（未設定）	スマートフォンに接続できない場合に get_live_frame が返すローカル JPEG パス

---

セキュリティ

ローカルネットワークのみ。 PC 側のサービスはすべてのインターフェースにバインドしますが、アプリケーション層でプライベート IP アドレス以外からの接続を拒否します。インターネットに公開することを想定していません。

HMAC リクエスト署名。 ペアリングトークンが平文で送信されることはありません。認証済みの各リクエストは、HKDF-SHA256 によってペアリングトークンから導出された署名キー（暗号化キーとは別のキー）を使い、METHOD\npath\ntimestamp\nnonce\nalgorithm に対する HMAC-SHA256 で署名され、X-Ts／X-Nonce／X-Sig／X-Enc ヘッダーを含みます。サーバーは一定時間で署名を検証し、±300 秒の範囲外のタイムスタンプと、再利用されたノンスを拒否します。そのため、傍受したリクエストを再送したり、通信経路からトークンを盗み取ったりすることはできません。新しい Android インストールでは、128 ビットのランダムなトークンが生成され、ペアリング後にスマートフォンと ~/.onsense/pair.json（chmod 600）に保存されます。（/health エンドポイントは認証されません。）正確なワイヤ形式については、PROTOCOL.md を参照してください。

プルとクリップボードへの自動注入はデフォルトで無効です。 GET /clip（スマートフォンによる PC クリップボードの取得）と OS クリップボードへの自動注入（スマートフォンからのプッシュ → Ctrl+V）は、--allow-pull または --set-clipboard を明示的に渡さない限り無効です。

暗号化された本文（AES-256-GCM）。 機密性の高いペイロード（カメラ映像、写真、センサーデータ、ファイル、クリップボードの内容）は、AES-256-GCM を使ってスマートフォンと PC の間で暗号化されます（間にクラウドは介在しないため、復号できる第三者はいません）。キーは HKDF-SHA256 によってペアリングトークンから導出されます（署名キーとは別のキー）。各メッセージでは新しい 96 ビットのノンスを使用し、GCM タグによって本文が認証され、リクエストに結び付けられるため、改ざんやレスポンスの差し替えは拒否されます。同じ Wi-Fi 上で受動的に通信を傍受しても、見えるのは暗号文だけです。機密性の低いメタデータは平文のままです。対象は、公開されている /version および /health エンドポイント、HTTP エラーレスポンス、プッシュ後に返される保存ファイルのパスです。（注：現在、大容量の転送では暗号化／復号中に本文全体がメモリにバッファーされます。非常に大きなファイルのチャンク単位のストリーミングは今後の対応予定です。トランスポート層の TLS による追加強化も、今後の選択肢です。）

ファイルサイズの上限。 ONSENSE_CLIP_MAX_MB（デフォルトは 200 MB）を超える受信プッシュは拒否されます。上限をなくすには 0 に設定してください。

脆弱性の報告。 セキュリティ上の問題は非公開で報告してください。SECURITY.md を参照してください。セキュリティに関する報告を公開の Issue として投稿しないでください。

---

ライセンス

MIT です。LICENSE を参照してください。