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等の座標ベース自動化には、テスト自動化の現場でよく遭遇する構造的な限界があります。本ツールはそれらを、ドライバレベルで合成入力を注入することで回避します。

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

Related MCP server: ScreenHand

アーキテクチャ

flowchart TB
    Client["MCPクライアント<br/>(Claude Desktop / Claude Code など)"]

    subgraph Server["openinputbridge-mcp (Node.js/TypeScript)"]
        direction TB
        McpServer["MCP Server<br/>(stdio transport, ネットワーク非公開)"]
        Safety["Safety Gate<br/>arm必須化 + レート制限"]
        Bridge["OibBridge<br/>JSON Linesクライアント"]
        McpServer --> Safety --> Bridge
    end

    subgraph Helper["oib_bridge.exe (自作Cヘルパー, MIT)"]
        direction TB
        StdioLoop["stdin/stdout<br/>JSON Lines プロトコル"]
        Watchdog["排他モード<br/>ウォッチドッグスレッド"]
        Ioctl["DeviceIoControl呼び出し"]
        StdioLoop --> Ioctl
        Watchdog -.監視.-> Ioctl
    end

    subgraph Driver["OpenInputBridgeドライバ"]
        direction TB
        Devices["\\.\interception00-19<br/>(コントロールデバイス)"]
        Filter["oib_kbd.sys / oib_mou.sys<br/>(キーボード/マウス フィルタドライバ)"]
        Devices --> Filter
    end

    Target["対象アプリケーション<br/>(実際のキーボード/マウス入力として着弾)"]

    Client -- "MCPプロトコル (stdio, JSON-RPC)" --> McpServer
    Bridge -- "子プロセスspawn<br/>stdin/stdout (JSON Lines)" --> StdioLoop
    Ioctl -- "IOCTL_WRITE / IOCTL_SET_FILTER 等" --> Devices
    Filter -- "合成入力として注入<br/>(実HIDスタックと同じ経路)" --> Target

• stdioトランスポートのみ。ネットワークリスナーは一切持ちません。MCPクライアントがローカルでサブプロセス起動する通常の使い方のみを想定しています。

• ヘルパー(oib_bridge.exe)とドライバの間は docs/PROTOCOL.md を単一の仕様源とし、third_party/interception(LGPL)には一切依存しません。

• MCPサーバー(Node.js)とヘルパー(C)の間は、1行1JSONオブジェクトの単純なリクエスト/レスポンスプロトコルです。

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

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

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(日本語)配列を自動選択します(layoutパラメータで明示指定も可能)。US/JIS双方とも実機で検証済みです(test/REALWORLD_TESTING.md参照)。US/JIS以外のレイアウトは現状未対応(USとして扱われます)。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++ ビルドツール) — 事前ビルド済みバイナリの配布は今後の予定です(下記「既知の制限」参照)

クイックスタート

git clone https://github.com/Applet-LLC/OpenInputBridge-MCP.git
cd OpenInputBridge-MCP
npm install
npm run build

# C ヘルパーのビルド (Visual Studio Developer PowerShell/コマンドプロンプトで)
cl.exe /nologo /W4 /utf-8 /Fe:helper\oib_bridge.exe helper\oib_bridge.c

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

{
  "mcpServers": {
    "openinputbridge": {
      "command": "node",
      "args": ["C:\\path\\to\\OpenInputBridge-MCP\\dist\\index.js"]
    }
  }
}

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

既知の制限

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

• US/JIS配列に対応(type_textが呼び出しごとにフォーカス中ウィンドウのレイアウトを自動検出、明示指定も可)。それ以外のレイアウト(独/仏配列等)は現状未対応で、USとして扱われます。IME経由のひらがな/漢字変換入力はスコープ外

• JIS配列の「¥」キーは(Windowsの既知の仕様により)実際にはASCIIバックスラッシュを送出し、真のyen記号文字(U+00A5)をtype_textで入力する手段はありません(物理キーそのものはpress_key({key:"IntlYen"})で押せます)

• type_textでShift状態を1文字ごとに切り替える極端なパターン(例: "MiXeD")は、タイミング対策後も一部の文字でShiftが反映されないことがあります。通常の英文・識別子等では問題にならないことを確認済みです

• マウスの相対移動(mouse_move, absolute:false)はOSのポインタ加速の影響を受けるため、指定した移動量とカーソルの実際の移動量は一致しません(物理マウスと同じ経路のため、想定通りの挙動)

• マウスの絶対移動(absolute:true)の正規化座標系(マルチモニタ・DPIスケーリング環境での基準)は未特定です。使用前に対象環境での着地点を確認することを推奨します

• Windows専用

• 読み取り・監視系ツールなし(意図的、上記参照)

• 事前ビルド済みバイナリ未配布: 現状 helper/oib_bridge.c を利用者自身がビルドする必要があります。GitHub Actionsでのビルド・npm公開は今後のマイルストーンです

セキュリティ

このツールが持つ能力(無昇格プロセスからのシステム全体入力の注入)のリスクと、実装済みの安全機構については SECURITY.md を必ず読んでください。

ロードマップ

今後の検証・改善候補(優先度未確定、詳細は test/REALWORLD_TESTING.md の「未実施の検証」参照):

• 排他モード有効化中にoib_bridge.exeを強制終了した場合の、ドライバ側クリーンアップによる自動復元の実機検証

• mouse_clickの座標精度・ボタン別動作の個別検証

• マウス絶対移動(absolute:true)の座標系(マルチモニタ・DPIスケーリング環境)の正確な仕様特定

• US/JIS以外のキーボードレイアウト対応

ライセンス

MIT。third_party/interception(LGPL)のコードには一切依存していません。

Contributors

• Applet-LLC — プロジェクトオーナー

• Claude(Anthropic、Claude Code 経由)— 実装・実機検証・ドキュメント作成に貢献