openinputbridge-mcp weekly downloads statistics

OpenInputBridge-MCP

OpenInputBridge(Interception互換のカーネルレベル キーボード/マウス入力ドライバ)を、MCP (Model Context Protocol) 経由のツールとして公開するサーバーです。

GUI/ネイティブアプリのテスト自動化における SendInput() / UI Automation / 座標ベース自動化ツールの代替・上位互換として、AIエージェント(Claude Codeなど)やテストコードから、カーネルレベルの合成キーボード/マウス入力を送信できます。

⚠️ 本プロジェクトは oblitum/Interception(LGPL/商用デュアルライセンス)のコードには一切依存していません。ヘルパー実行ファイル(helper/oib_bridge.c)は、OpenInputBridge本体の docs/PROTOCOL.md に文書化されたワイヤプロトコルのみを根拠に、独自にIOCTLを実装しています。

これは何のためのツールか

SendInput() / UI Automation / PyAutoGUI・Selenium等の座標ベース自動化には、テスト自動化の現場でよく遭遇する構造的な限界があります。本ツールはそれらを、ドライバレベルで合成入力を注入することで回避します。

| よくある失敗パターン | 原因 | 本ツールでの解決 |

| 管理者権限で起動したアプリに入力が届かない | UIPI (User Interface Privilege Isolation) により、非管理者プロセスからの合成入力が上位integrity levelのウィンドウにブロックされる | カーネルドライバ層でHIDスタックに直接介在するため、送信元プロセスのintegrity levelに依存しない | | RDP/仮想マシン/CI専用機で不安定 | 仮想ディスプレイやリモートセッションでは、SendInput が前提とするフォアグラウンドウィンドウ/デスクトップの扱いが環境依存になりやすい | ドライバはセッションが物理/仮想いずれであってもHIDスタック側で動作する | | UI Automation/PyAutoGUIが解像度・DPI変更で壊れる | 画面座標やUI要素のプロパティに依存する | キーのメイクコード/マウスの相対移動量ベースで送信するため、解像度非依存 | | 一部アプリが合成入力(SendInput由来)を区別・無視する | アプリによっては SendInput のフラグやRAW_INPUTの出自を見て弾く実装がある | 物理デバイスと同じ経路(KEYBOARD_INPUT_DATA/MOUSE_INPUT_DATA)でHIDスタックに入るため、アプリ側から区別しにくい |

注意: 上記はあくまで技術的な限界の回避策であり、「検知されない」ことを保証するものではありません。カーネルレベルのフィルタドライバ自体が検知され得ることは SECURITY.md に記載しています。自分が権限を持つ/管理しているテスト環境以外(他社のゲーム・アプリのアンチチート回避目的など)での利用は想定しておらず、対象ソフトウェアの利用規約に違反する可能性がある用途には使用しないでください。

アーキテクチャ

• stdioトランスポートのみ。ネットワークリスナーは一切持ちません。MCPクライアントがローカルでサブプロセス起動する通常の使い方のみを想定しています。 • ヘルパー(oib_bridge.exe)とドライバの間は docs/PROTOCOL.md を単一の仕様源とし、third_party/interception(LGPL)には一切依存しません。 • MCPサーバー(Node.js)とヘルパー(C)の間は、1行1JSONオブジェクトの単純なリクエスト/レスポンスプロトコルです。

できること(v1ツール一覧)

送信専用です。物理入力の内容を読み取る/監視するツールは意図的に含んでいません(詳細は SECURITY.md)。

| ツール | できること |

| enable_input_control | このセッションで送信系ツールを有効化する(最初に必ず1回呼ぶ必要がある) | | disable_input_control | 送信系ツールを無効化する | | get_driver_status | ドライバのインストール状況・バージョン・キーボード/マウスのスロット構成を確認する(診断用、armなしで呼べる) | | press_key | 1キーをタップ(押して離す)。Ctrl+A等の修飾キー同時押しにも対応 | | key_down / key_up | キーを押しっぱなしにする/離す(複合ジェスチャ用) | | type_text | 文字列をキーストローク列として送信する(US/JIS/独/仏/露配列は自動判定対応、韓国語字母・台湾注音符号は明示指定) | | mouse_move | マウスを相対/絶対移動する(絶対移動はvirtualDesktop:trueでマルチモニタ全体を対象にできる) | | mouse_click | マウスボタン(左/右/中/X1/X2)のクリック・押下・解放 | | mouse_wheel | 垂直/水平ホイールのスクロール | | enable_exclusive_input_mode | 排他モード: 物理キーボード/マウスの入力を全スロットで捕捉・破棄し、このセッションからの合成入力だけを対象アプリに届ける(CI/専用テスト機向け、要armかつ強い注意が必要) | | disable_exclusive_input_mode | 排他モードを解除する(armなしでも常に呼び出せるエスケープハッチ) | | get_exclusive_mode_status | 排他モードが現在有効かどうかを確認する |

AIエージェントが知っておくべき仕様

このMCPサーバーを操作するAIエージェント(あるいはそれを実装する開発者)は、以下を理解しておく必要があります。

1. 送信前に必ず enable_input_control を呼ぶ

サーバー起動直後は全ての送信系ツール(press_key等)が NotArmedError で拒否されます。MCPクライアント自体のツール許可UIとは別に、このドライバ固有の強力さに見合ったもう一段の明示的な同意ステップです。セッション中に1回呼べば、以降はそのプロセスが生きている間は有効です。

2. キー名はDOM KeyboardEvent.code 語彙

press_key/key_down/key_up の key パラメータは、Playwright/Seleniumのテスト自動化エンジニアに馴染みのある DOM KeyboardEvent.code 命名(KeyA〜KeyZ, Digit0〜Digit9, Enter, ArrowUp, ShiftLeft, F1〜F12 等、JIS配列専用のIntlRo/IntlYen/Convert/NonConvert/KanaModeも含む)を使います。完全な一覧は src/keycodes.ts の KEY_TABLE を参照してください。これらは物理キー位置ベースなのでレイアウトに依存せず動作します。

type_text は入力された文字からキー+Shift状態を逆算する必要があり、これはOS側のアクティブなキーボードレイアウトに依存します。既定(layout: "auto")では、フォーカス中のウィンドウの入力ロケールを呼び出しごとに検出し、us/jis(日本語)/de(ドイツ語QWERTZ)/fr(フランス語AZERTY)/ru(ロシア語ЙЦУКЕН)を自動選択します(layoutパラメータで明示指定も可能)。US/JISのみ実機で検証済みです(test/REALWORLD_TESTING.md参照)。独/仏/露は標準的なレイアウト仕様を基にした未検証の実装です。

ko(韓国語2ベルシク)・tw(台湾注音符号)もlayoutパラメータで明示指定できますが、IMEによる合成(ハングル音節・漢字への変換)は行わず、字母/注音記号を1文字ずつそのまま送信します(例: layout:"ko"で"r"+"k"を送ると、合成された音節「가」ではなく字母「ㄱ」「ㅏ」が個別に送信される)。この2つは自動判定の対象外です — 同じ韓国語/繁体中国語キーボードレイアウトのままIMEのON/OFF状態だけが切り替わることがあり、レイアウトのLANGIDだけからは判別できないため、明示的にlayoutを指定した場合のみ有効になります。

中国語(拼音入力)を扱う場合は layout: "us"(または "auto")を使ってください。 中国語入力で主に使われる拼音(ピンイン)方式は、物理キーボード自体はUS配列(QWERTY)そのままで、ローマ字を打鍵した内容をIMEが漢字に変換する仕組みのため、専用のキー配列テーブルは不要です。ただしこれも他の言語と同様、実際のIME変換(拼音→漢字)はスコープ外です。type_text はローマ字までしか送れず、続く候補選択・確定はこのMCPサーバーの対象外です。注音符号(ボポモフォ)方式で入力したい場合のみ、上記の layout: "tw" で未合成の注音記号を送信できます。

上記いずれのレイアウトも、実際のIME変換(ひらがな/漢字、ハングル音節合成、拼音→漢字等)を経由した入力はスコープ外です。

3. type_text は全体を検証してから送信する(部分的な副作用なし)

未対応文字(非ASCII等)が1文字でも含まれる場合、何も送信せずエラーを返します。途中まで入力されて残りが失敗する、という状態にはなりません。

4. デバイススロットの境界は可変

\\.\interception00〜19 の20スロットのうち、どこまでがキーボードでどこからがマウスかは、ドライバのインストール時設定(KeyboardSlotCount)次第で変わります(デフォルトは10/10)。ツール側のデフォルト値(キーボード系はdevice=0、マウス系はdevice=10)は既定構成を前提にしているため、複数デバイス/非既定構成を扱う場合は get_driver_status の keyboardSlotCount/mouseSlotCount を先に確認してください。

5. レート制限がある

既定では10秒間に最大500入力イベントまで(環境変数 OIB_MCP_RATE_LIMIT_MAX / OIB_MCP_RATE_LIMIT_WINDOW_MS で変更可能)。暴走したエージェント(プロンプトインジェクション含む)が入力を連射し続けることを防ぐためのものです。超過すると RateLimitError が返ります。

6. 排他モードは強力・危険。CI/専用テスト機以外では使わない

enable_exclusive_input_mode を有効化すると、オペレーターが物理キーボード/マウスを操作しても対象アプリには一切反映されなくなります。日常利用中のPCで有効化すると物理入力が使えなくなるため、無人のテスト実行環境(CI・専用テスト機)での利用のみを想定しています。

• ハートビートが一定時間(既定5秒、watchdogTimeoutMsで設定可)途絶えると自動的に解除されます • disable_exclusive_input_mode は arm状態やレート制限に関係なく常に呼び出せます • MCPサーバーやAIエージェント自体が応答不能になった場合の最終手段として、oib_bridge.exe プロセスを終了させると、ドライバ側の仕組みにより即座に物理入力が復元されます(Interceptionプロトコルのハンドルクローズ時クリーンアップによるもので、他のいかなるプロセスもこれを代替できません)。詳細は SECURITY.md を参照してください。

7. v1には「読み取り・監視系」ツールがない

物理キーボード/マウスの入力内容をAIエージェントに渡すツール(IOCTL_READ/interception_receive相当)は意図的に実装していません。これは「MCP経由でAIがシステム全体のキー入力を盗聴できる」という最も深刻な悪用シナリオを設計上排除するためです。

前提条件

• Windows専用(OpenInputBridge自体がWindows専用のため) • OpenInputBridge ドライバがインストール済み・起動していること(sc.exe query OpenInputBridgeKeyboard / OpenInputBridgeMouse が RUNNING) • Node.js 18以上 • ヘルパー実行ファイルのビルドに Visual Studio 2022 (C++ ビルドツール) — 事前ビルド済みバイナリの配布は今後の予定です(下記「既知の制限」参照)

クイックスタート

npm公開後は npx openinputbridge-mcp でのビルド不要インストールを予定していますが、現時点では未公開のため上記のソースビルドが必要です(詳細は「既知の制限」参照)。

MCPクライアント(例: Claude Code の .mcp.json)に登録します。

接続後、まず get_driver_status でドライバが認識されているか確認し、enable_input_control を呼んでから各ツールを使用してください。

既知の制限

実機(OpenInputBridgeインストール環境)での検証を実施済みです。詳細は test/REALWORLD_TESTING.md を参照してください。…

Description from the npm listing.