uMouse MCP

uMouse MCP — AI エージェント向けハードウェアマウス制御

英語 | 简体中文

AI エージェントに実際のハードウェアマウスを使わせましょう。uMouse MCP は、Windows での USB HID マウス制御と音声ディクテーションに対応する Model Context Protocol（MCP）サーバーです。マウスの移動、クリック、スクロール、ドラッグには互換性のある uMouse デバイスを使用します。音声入力では、プラグイン可能な音声認識プロバイダーに対応しています。

互換性のある uMouse ハードウェアとファームウェア、Windows x64、および別途インストールした Node.js ランタイム（Node.js 22 x64 を使用）が必要です。 通常の USB マウスでは動作しません。MIT ライセンスの対象はサーバーコードです。ネイティブ SDK バイナリには別途利用条件があります。ライセンスをご覧ください。

ダウンロード · クイックスタート · デモリファレンス · ドキュメント · ハードウェアの入手／サポート · uMouse SDK

ダウンロード

パッケージ	ダウンロード	要件
MCPB · Windows x64 · v0.1.1	MCPB をダウンロード · リリースノートと SHA-256	MCPB 対応クライアント、互換性のある uMouse ハードウェア、x64 Node.js 22 以降
Windows x64 · v0.1.0	ZIP をダウンロード · リリースノートと SHA-256	互換性のある uMouse デバイスとファームウェア、別途インストールした Node.js

すべてのリリース · Gitee リリースミラー

MCPB のインストール： .mcpb を、MCPB Node 拡張機能に対応したクライアントにインポートしてください。バージョン 0.1.1 は従来の 0.1.0 ランタイムをラップしたもので、クラウド認証情報は含まず、音声認識はデフォルトで disabled に設定されています。windows-speech はオプションのローカルプロバイダーです。データの保存先はデフォルトで ~/.umouse-mcp-mcpb です。MCPB バイリンガルガイドをご覧ください。公式 MCP Registry に io.github.SonicloudTech/mouse-mcp として公開されています。メタデータは server.json、公開と検証についてはこちらをご覧ください。

ZIP には、本番用の Node 依存関係、ネイティブ SDK DLL、音声プレビュー UI、VC ランタイムライブラリが含まれています。リリース版の使用に npm install やコンパイルは必要ありません。ただし、Node.js 自体は同梱されていません。

リリース版とソース版ではインストール方法が異なります： v0.1.0 インストーラーは、従来の stdio エントリである mcp/dist/index.js を登録します。以下で説明する shared-v2 ツール、ネイティブホスト、受け入れテストラボは、ソース実装に含まれます。この ZIP は shared-v2 の完全なバンドルではなく、そのネイティブホストや受け入れテストラボは含まれていません。リリース版固有の動作については、インストール済みサーバーのツール一覧と、ZIP に同梱されている README をご確認ください。

クイックスタート

以下の手順では、元の ZIP を使用します。MCPB の場合は、上記のインポート手順に従ってから、手順 5 でステータスとデバイスを確認してください。

1. Node.js 22 x64 をインストールし、node --version が動作することを確認します。互換性のある uMouse の USB レシーバー／デバイスを接続し、マウスの電源を入れます。デバイスまたはファームウェアの互換性を確認するには、ハードウェアとサポートを参照してください。
2. 上記の ZIP をダウンロードして展開します。umouse-mcp-os-win-x64 フォルダーを開きます。クライアント設定でこのフォルダーを参照するため、恒久的な場所に保存してください。
3. install-agents.cmd をダブルクリックしてユーザースコープで ZCode を登録するか、展開したフォルダーから、使用するクライアントに対応したコマンドを1 つ実行します。

クライアント	PowerShell コマンド
ZCode	node mcp/scripts/install-agents.mjs zcode
Claude Desktop	node mcp/scripts/install-agents.mjs claude
Cursor	node mcp/scripts/install-agents.mjs cursor

インストーラーは、選択したクライアントの設定に umouse エントリを追加または更新します。また、設定がまだ存在しない場合は、同梱の試用版 ASR 設定をローカルデータディレクトリにコピーします。本番環境で使用する場合は、試用用の認証情報を独自のものに置き換えてください。

4. 使用するクライアントに応じて、新しい ZCode セッションを開くか、Claude Desktop を完全に終了して再起動するか、Cursor のウィンドウを再読み込みします。
5. エージェントに umouse_status、umouse_get_capabilities、umouse_list_devices を呼び出すよう依頼します。SDK の状態、デバイス一覧、報告された機能を確認してください。返された sdkVersion で確認できるのは SDK へのアクセスのみであり、ハードウェアを操作できることの証明にはなりません。依頼したマウス操作の結果が画面上で確認できることを確かめてから、操作を信頼してください。

mcpServers JSON 形式を受け付けるクライアントでは、展開したフォルダーのパスに置き換えて、このエントリを手動で追加します。他のクライアントでは、異なる設定形式が必要な場合があります。

{
  "mcpServers": {
    "umouse": {
      "command": "node",
      "args": ["C:\\path\\to\\umouse-mcp-os-win-x64\\mcp\\dist\\index.js"]
    }
  }
}

手動で設定しても、インストーラーによる ASR のセットアップは実行されません。音声入力が必要な場合は、音声プロバイダーを別途設定してください。音声入力を参照してください。

ソースを開発する場合、npm ci、npm run build、npm test によって、依存関係をインストールし、TypeScript をビルドして、デフォルトのテストを実行します。これらのコマンドでは、完全な shared-v2 ネイティブバンドルは生成されません。完全な shared-v2 の一般公開向けパッケージ作成ワークフローは、まだ用意されていません。shared-v2 の開発とメンテナンスに関するメモ（中国語）とネイティブホストのビルドに関するメモ（中国語）は、この別の開発方法に関する参考資料です。

デモ

マウスラボの録画は、shared-v2 のソース実装を示すものであり、従来の ZIP インストールを示すものではありません。

ハードウェアマウスで実際のブラウザーラボページを操作（録画に重ねた金色の矢印はシステムカーソル）— カウンター、ホイール、ヒットのフィードバックはすべて実際のブラウザーイベントによるものです。

音声入力：話すと、どのウィンドウにも入力されます

デバイスの音声キーを長押しして話し、キーを放すと、認識されたテキストが現在フォーカスされているウィンドウに入力されます。どちらの動画も 1080p でライブ録画したものです。

エージェントクライアント（ターミナル） — 話したコマンドが入力され、実行されます。

mcp/acceptance/demo/voice-typing-agent.mp4

動画を開く／ダウンロードする

WeChat — 話したメッセージが入力欄に入力され、送信されます。

mcp/acceptance/demo/voice-typing-wechat.mp4

動画を開く／ダウンロードする

Shared-v2 の機能（ソース実装）

モデル → MCP ホスト → 共有デーモン（:47192）→ C++ ネイティブホスト → USB HID 0xF0/0xF1 → uMouse デバイス → Windows 入力パイプライン

• ハードウェア操作：umouse_mouse_action — デスクトップの物理ピクセル座標での移動／クリック／スクロール／ドラッグ。負の座標を含むマルチモニターに対応し、precision: standard | high を指定できます。
• タスクの排他制御：umouse_control の begin → 操作 → end の間、マウスとキーボードを操作できるタスクは一度に 1 つだけです。切断された接続は自動的にクリーンアップされます。
• 読み取り専用センサー：umouse_input_status — カーソル位置、キーのリアルタイム状態、フォアグラウンドウィンドウの識別情報を取得します。読み取り専用で、入力を横取りすることはありません。
• 音声ディクテーション：マイクの取り込み → VAD による分割 → 差し替え可能な ASR プロバイダー → プレビュー／最終文字起こし。マウス制御を横取りしない独立した処理系です（下記参照）。
• 共有デーモン：マシンごとに 1 つのインスタンス（ポート 47192）が起動し、ZCode／Codex／Claude の各ホスト間で共有されます。アイドル状態になると終了します。

音声ディクテーション：差し替え可能な ASR プロバイダー

ここでの ASR は、特定のベンダーに紐づくブラックボックスではありません。小さなインターフェイス契約であり、begin / writePcm / finishInput / cancel を実装し、preview / segmentFinal / warning / terminal を（それぞれ 1 回だけ）出力すれば、有効なプロバイダーになります。認識サービスを切り替えるには、ファクトリー関数を 1 つ差し替えるだけです。mcp/src/sinicloud-asr.ts は完全なリファレンス実装です。

プロバイダー（UMSDK_ASR_PROVIDER）	備考
sinicloud（Windows のレガシー ZIP／ソース版のデフォルト）	Sonicloud のオープンプラットフォームのストリーミング ASR：純粋な TypeScript で、DLL 依存なし。16k／16bit／モノラルの PCM をストリーミングし、途中経過のプレビューを提供します。ストリームを切断せずに残高不足を警告します。
windows-speech	Windows 組み込みの音声認識機能。オフラインで動作し、音声がマシンの外に送信されることはありません。
whisper-cpp	セルフホスト可能な whisper-cli と ggml モデル（パスを設定可能）によるオフラインの CPU 文字起こし
http	カスタム文字起こしエンドポイント：multipart WAV を送信し、{"text"} を受信します。
disabled	ディクテーションを無効にします。プロバイダーがない場合は、asr_unavailable にフォールバックします。

認証情報は設定経由でのみ渡され、セッションごとにホットリードされるため、再起動せずにキーを差し替えられます。デフォルトでは <data-dir>/sinicloud_asr.json にある JSON ファイル（appId / apiKey / apiSecret / userId / lanid / streamUrl / tokenUrl）を使用します。環境変数 UMSDK_ASR_APP_ID / UMSDK_ASR_API_KEY / UMSDK_ASR_API_SECRET / … はファイルの設定より優先されます。ハードコード、表示、ログ出力、コミットは一切されません。レガシー版 v0.1.0 ZIP にはオープンプラットフォーム用の試用認証情報が含まれています。本番環境では独自のキーに置き換えてください。v0.1.1 MCPB にはクラウド認証情報が含まれず、disabled（デフォルト）または windows-speech のみを受け付けます。ソースプロバイダーの完全な一覧については、mcp/SHARED-V2.md を参照してください。

Shared-v2 の適応型位置決め

Windows のポインターボールistics（「ポインターの精度を高める」）により、プロトコル上のドット数からピクセル数への変換倍率は振幅に応じて変化します。umouse-mcp には 11 段階のボールistics変換倍率カーブが組み込まれています。デバイスの初回使用時にローカルのポインター設定を読み取り専用でシード値に使用し、[0.125, 10] の範囲でフレームごとにオンライン学習します。60 秒間アイドル状態が続くとシード値に戻ります。マシンやデバイスを変更しても調整は不要です。シード値が古い場合は、フレームが 1～2 回余分に必要になります。設計と測定結果については、mcp/sdk-host/POSITIONING.md を参照してください。

指標	standard	high
停止許容誤差	残差 ≤ 4 px	残差 ≤ 1 px
測定値（リファレンス環境）	中央値 356 ms／2 フレーム	最大 1 px、平均 0.67 px
失敗時の動作	同一です。high では最悪の場合でもベストエフォートで ≤ 4 px にとどまり、残差はそのまま報告されます。

Shared-v2 のリファレンス受け入れテスト

Shared-v2 のビルド一式を準備した後、受け入れテストのセットアップガイドに従ってください。テスト環境はこのリポジトリ内にあり、v0.1.0 ZIP には含まれていません。

実際のブラウザーページ上でクローズドループにより動作を検証する 32 件のケースがあります。左／右／中央クリックの回数、ダブルクリックの間隔、ホイールの scrollTop、ドラッグの直線性、1 px のブルズアイへの命中を確認します。

cd mcp/acceptance
$env:UMCFG = "C:\path\to\client.json"
$env:UMBUNDLE = "C:\path\to\shared-v2-bundle"
node run-matrix.mjs
# Writes acceptance-report.json; the documented reference run passed 32/32 cases.

Shared-v2 のセキュリティと検証

• 画面ロック中／UAC／セキュアデスクトップ：キー操作は button_feedback_input_desktop_unavailable で拒否されます。これは安全上の仕様であり、不具合ではありません。
• effectConfirmed は常に false です。トランスポートの成功はアプリケーションへの反映を意味しません。正解となるのは、受け入れテスト用ラボで取得したページの証拠です。
• ASR の認証情報はローカル設定ファイルと環境変数からのみ入力します。コミット、表示、ログへの出力は決して行いません。recover には、--hardware-reset-confirmed を指定する人間の操作が必要です。

ドキュメント

ドキュメント	内容
mcp/SHARED-V2.md	Shared-v2 のインストール、アップグレード、メンテナンス、復旧
mcp/acceptance/MOUSE-CAPABILITY-TESTS.md	32 ケースのカタログ（コピー＆ペースト可能な MCP 呼び出しと合格基準）
mcp/sdk-host/POSITIONING.md	弾道的な位置決め：経緯、アルゴリズム、デバイス間の比較表
mcp/README.md	MCP ツールの完全なリファレンス（中国語）

ハードウェアとサポート

互換デバイス、評価用ユニット、またはファームウェアの確認が必要な場合は、対象プラットフォーム、デバイスモデル、ファームウェアのバージョン、想定するユースケースを添えて、[email protected] までお問い合わせください。

ソフトウェアクラウドテック（SonicloudTech）（安徽ソニクラウド知能技術有限公司）が保守しています — AI 入力ハードウェアと音声オープンプラットフォームを提供しています。

• ウェブサイト：https://sinicloud.com/
• 音声オープンプラットフォーム：https://open.sinicloud.com/ — デフォルトの ASR プロバイダーを提供します。サインアップして試用枠をご利用ください。
• ビジネスおよび技術に関するお問い合わせ：[email protected] — OEM／販売代理／カスタムファームウェア／共同開発について。対象プラットフォーム、想定販売数量、デバイスモデル、ファームウェアのバージョン、想定するユースケースを記載してください。

関連プロジェクト：uMouse SDK

スマートマウスのハードウェアを独自のアプリケーションに統合しますか？ uMouse SDK は、USB HID／BLE デバイス接続、キーイベント、オーディオ向けの C ABI を提供します。英語版 SDK README、統合ガイド、または SDK のダウンロードから始めてください。SDK には独自のプラットフォームおよびライセンスの対応表があります。これらのプラットフォームオプションによって、この MCP サーバーの対応範囲が Windows x64 を超えることはありません。単体の SDK パッケージで代用せず、各 MCP リリースに同梱されているネイティブ SDK DLL を使用してください。

ロードマップ

• マシン間で適応するゲイン曲線（v0.4）
• プラグイン可能な ASR プロバイダー：sinicloud ストリーミング、認証情報を完全に設定可能
• ファームウェアで実行する 1～2 カウントの微調整フレーム
• ホイール ACK とスクロール量のクローズドループ制御
• 絶対位置指定モード

ライセンス

MCP サーバーのコードは MIT ライセンスの下で公開されています。ネイティブ SDK は、公開ヘッダー（include/umouse_sdk.h）とともに、ソース非公開の DLL として提供されます。