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）之间采用每行一个 JSON 对象的简单请求/响应协议。

功能（v1 工具列表）

仅限发送。有意不包含读取/监控物理输入内容的工具（详见 SECURITY.md）。

AI 代理需要了解的规范

操作此 MCP 服务器的 AI 代理（或实现它的开发者）需要理解以下内容。

1. 发送前必须调用 enable_input_control

服务器启动后，所有发送类工具（press_key 等）都会被 NotArmedError 拒绝。这是与 MCP 客户端本身的工具许可 UI 不同的、与该驱动特有的强大能力相匹配的又一层明确同意步骤。在会话中调用一次后，在该进程存活期间持续有效。

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 状态，这依赖于操作系统侧当前激活的键盘布局。默认（layout: "auto"）会在每次调用时检测焦点窗口的输入区域设置，自动选择 US/JIS（日语）布局（也可通过 layout 参数显式指定）。US/JIS 均已在实机上验证（参见 test/REALWORLD_TESTING.md）。US/JIS 以外的布局目前不支持（按 US 处理）。通过 IME 的平假名/汉字转换输入不在范围内。

3. type_text 会先整体验证再发送（无部分副作用）

如果包含哪怕一个不支持的字符（非 ASCII 等），则不发送任何内容并返回错误。不会出现输入到一半然后剩余部分失败的状态。

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）有意未实现。这是为了在设计上排除"AI 可以通过 MCP 窃听整个系统的按键输入"这一最严重的滥用场景。

前提条件

• 仅限 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 反斜杠，无法通过 type_text 输入真正的日元符号字符（U+00A5）（物理键本身可以通过 press_key({key:"IntlYen"}) 按下）

• type_text 中每个字符切换 Shift 状态的极端模式（例如 "MiXeD"）即使在时序对策后，部分字符的 Shift 仍可能不生效。已确认在普通英文、标识符等场景下没有问题

• 鼠标相对移动（mouse_move，absolute:false）受操作系统指针加速的影响，因此指定的移动量与光标实际移动量不一致（与物理鼠标路径相同，属于预期行为）

• 鼠标绝对移动（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）— 参与实现・实机验证・文档编写