OpenInputBridge-MCP

A server that exposes OpenInputBridge (an Interception-compatible kernel-level keyboard/mouse input driver) as tools via MCP (Model Context Protocol).

As an alternative and superior-compatible replacement for SendInput() / UI Automation / coordinate-based automation tools in GUI/native application test automation, it allows AI agents (such as Claude Code) and test code to send kernel-level synthetic keyboard/mouse input.

⚠️ This project does not depend on any code from oblitum/Interception (LGPL/commercial dual license). The helper executable (helper/oib_bridge.c) implements its own IOCTLs based solely on the wire protocol documented in the OpenInputBridge main project's docs/PROTOCOL.md.

What is this tool for?

SendInput() / UI Automation / coordinate-based automation tools such as PyAutoGUI and Selenium have structural limitations that are commonly encountered in test automation. This tool circumvents them by injecting synthetic input at the driver level.

Note: The above is merely a workaround for technical limitations and does not guarantee that it "cannot be detected." The fact that kernel-level filter drivers themselves can be detected is documented in SECURITY.md. Use outside of test environments you own/are authorized to manage (such as circumventing anti-cheat in other companies' games/apps) is not intended, and do not use it for purposes that may violate the terms of service of the target software.

Related MCP server: ScreenHand

Architecture

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 transport only. It does not have any network listeners. It only assumes the normal usage where the MCP client launches it as a local subprocess.

• Between the helper (oib_bridge.exe) and the driver, docs/PROTOCOL.md serves as the single source of truth, with no dependency on third_party/interception (LGPL).

• Between the MCP server (Node.js) and the helper (C), it uses a simple request/response protocol with one JSON object per line.

What it can do (v1 tool list)

Send-only. Tools that read/monitor physical input content are intentionally not included (see SECURITY.md for details).

Specifications AI agents should know

AI agents operating this MCP server (or developers implementing one) need to understand the following.

1. Call enable_input_control before sending

Immediately after server startup, all send-related tools (such as press_key) are rejected with NotArmedError. Apart from the MCP client's own tool permission UI, this is an additional explicit consent step commensurate with the power of this driver. Once called during a session, it remains valid for the lifetime of that process.

2. Key names use the DOM KeyboardEvent.code vocabulary

The key parameter of press_key/key_down/key_up uses the DOM KeyboardEvent.code naming familiar to Playwright/Selenium test automation engineers (KeyA–KeyZ, Digit0–Digit9, Enter, ArrowUp, ShiftLeft, F1–F12, etc., including JIS-layout-specific IntlRo/IntlYen/Convert/NonConvert/KanaMode). See the KEY_TABLE in src/keycodes.ts for the complete list. These are based on physical key positions, so they work independently of layout.

type_text must reverse-calculate the key+Shift state from the input characters, which depends on the active keyboard layout on the OS side. By default (layout: "auto"), it detects the input locale of the focused window on each call and automatically selects US/JIS (Japanese) layout (explicit specification is also possible via the layout parameter). Both US and JIS have been verified on real hardware (see test/REALWORLD_TESTING.md). Layouts other than US/JIS are currently unsupported (treated as US). Hiragana/Kanji conversion input via IME is out of scope.

3. type_text validates everything before sending (no partial side effects)

If even one unsupported character (non-ASCII, etc.) is included, it returns an error without sending anything. It will never end up in a state where part of the input is entered and the rest fails.

4. Device slot boundaries are variable

Of the 20 slots \\.\interception00–19, how many are keyboards and where mice begin depends on the driver's installation-time setting (KeyboardSlotCount) (default is 10/10). The tool-side defaults (keyboard tools use device=0, mouse tools use device=10) assume the default configuration, so when handling multiple devices/non-default configurations, first check keyboardSlotCount/mouseSlotCount in get_driver_status.

5. There is a rate limit

By default, up to 500 input events per 10 seconds (changeable via the environment variables OIB_MCP_RATE_LIMIT_MAX / OIB_MCP_RATE_LIMIT_WINDOW_MS). This is to prevent a runaway agent (including prompt injection) from continuously spamming input. Exceeding it returns RateLimitError.

6. Exclusive mode is powerful and dangerous. Do not use it outside CI/dedicated test machines

When enable_exclusive_input_mode is enabled, even if the operator operates the physical keyboard/mouse, nothing is reflected in the target app. Enabling it on a PC in daily use makes physical input unusable, so it is only intended for unattended test execution environments (CI/dedicated test machines).

• It is automatically disabled if the heartbeat is interrupted for a certain period (default 5 seconds, configurable via watchdogTimeoutMs)

• disable_exclusive_input_mode can always be called regardless of arm state or rate limits

• As a last resort if the MCP server or AI agent itself becomes unresponsive, terminating the oib_bridge.exe process immediately restores physical input through the driver-side mechanism (via the Interception protocol's handle-close cleanup, which no other process can substitute). See SECURITY.md for details.

7. v1 has no "read/monitor" tools

Tools that pass physical keyboard/mouse input content to the AI agent (equivalent to IOCTL_READ/interception_receive) are intentionally not implemented. This is to eliminate by design the most serious abuse scenario: "an AI can eavesdrop on all system key input via MCP."

Prerequisites

• Windows only (because OpenInputBridge itself is Windows-only)

• The OpenInputBridge driver is installed and running (sc.exe query OpenInputBridgeKeyboard / OpenInputBridgeMouse returns RUNNING)

• Node.js 18 or later

• Visual Studio 2022 (C++ build tools) to build the helper executable — distribution of pre-built binaries is planned for the future (see "Known limitations" below)

Quick start

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

Register it in your MCP client (e.g., Claude Code's .mcp.json).

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

After connecting, first check that the driver is recognized with get_driver_status, then call enable_input_control before using each tool.

Known limitations

Verification on real hardware (OpenInputBridge installed environment) has been completed. See test/REALWORLD_TESTING.md for details.

• Supports US/JIS layouts (type_text auto-detects the focused window's layout on each call; explicit specification is also possible). Other layouts (German/French, etc.) are currently unsupported and are treated as US. Hiragana/Kanji conversion input via IME is out of scope

• The JIS layout "¥" key (due to a known Windows specification) actually sends an ASCII backslash, and there is no way to input a true yen sign character (U+00A5) with type_text (the physical key itself can be pressed with press_key({key:"IntlYen"}))

• Extreme patterns in type_text that toggle the Shift state for each character (e.g., "MiXeD") may fail to reflect Shift for some characters even after timing countermeasures. It has been confirmed that this is not a problem for normal English text, identifiers, etc.

• Relative mouse movement (mouse_move, absolute:false) is affected by OS pointer acceleration, so the specified movement amount and the cursor's actual movement amount do not match (expected behavior, since it uses the same path as a physical mouse)

• The normalized coordinate system for absolute mouse movement (absolute:true) (the reference in multi-monitor/DPI scaling environments) is unspecified. It is recommended to verify the landing point in the target environment before use

• Windows only

• No read/monitor tools (intentional, see above)

• No pre-built binaries distributed: currently users must build helper/oib_bridge.c themselves. Building via GitHub Actions and npm publishing are future milestones

Security

Be sure to read SECURITY.md regarding the risks of this tool's capabilities (injection of system-wide input from a non-elevated process) and the implemented safety mechanisms.

Roadmap

Future verification/improvement candidates (priority undetermined, see "Unverified items" in test/REALWORLD_TESTING.md for details):

• Real hardware verification of automatic restoration via driver-side cleanup when oib_bridge.exe is force-terminated while exclusive mode is enabled

• Individual verification of mouse_click coordinate accuracy and per-button behavior

• Precise specification identification of the coordinate system for absolute mouse movement (absolute:true) (multi-monitor/DPI scaling environments)

• Support for keyboard layouts other than US/JIS

License

MIT. It does not depend on any code from third_party/interception (LGPL).

Contributors

• Applet-LLC — Project owner

• Claude (Anthropic, via Claude Code) — Contributed to implementation, real hardware verification, and documentation