Kira Mcp

   ██╗  ██╗██╗██████╗  █████╗
   ██║ ██╔╝██║██╔══██╗██╔══██╗
   █████╔╝ ██║██████╔╝███████║
   ██╔═██╗ ██║██╔══██╗██╔══██║
   ██║  ██╗██║██║  ██║██║  ██║
   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝  ╚═╝
        local · MCP · computer-use

kira-mcp 是一个本地 Model Context Protocol 服务，为任何兼容 MCP 的 Agent 宿主（Claude Desktop、Claude Code、Cursor、Cline、Continue 等）提供在主机上完整的计算机使用能力。

https://github.com/user-attachments/assets/b9b65987-32b1-43f5-bdf0-006ea71c6d13

Kira 端到端解决 CAPTCHA——只需一次 perceive_screen，即可获取可点击的像素坐标，无需人工介入。

专为 Windows 构建和调优。macOS 和 Linux 尽力支持——大多数工具都能正常工作，但部分 UI 习惯有所不同。

• 视觉——perceive_screen 是 Agent 用于“一次性查看屏幕”的工具。它会在内存中截取当前屏幕，运行本地 microsoft/OmniParser-v2 YOLO 图标检测器，并返回带标注的图像，以及包含每个元素 {id, bbox, cx, cy, confidence} 的 JSON，坐标为绝对屏幕像素——因此 Agent 可以将 cx, cy 直接传给 mouse_click。无需 API 密钥，也不会发起网络请求。
• 桌面自动化——通过 pyautogui、mss 和 pyperclip 实现像素级精准的鼠标控制、键盘输入（包括组合键和按键保持）以及剪贴板读写。

该服务使用 stdio JSON-RPC 通信，并由 Agent 宿主作为子进程启动。

快速开始

你需要 Python 3.10+ 和一个 MCP 宿主（示例使用 Claude Desktop）。选择你的操作系统。

pip install kira-mcp

{
  "mcpServers": {
    "kira-mcp": { "command": "kira-mcp" }
  }
}

pip install kira-mcp

{
  "mcpServers": {
    "kira-mcp": { "command": "kira-mcp" }
  }
}

sudo apt install python3-tk python3-dev scrot xdotool   # or your distro's equivalent
pip install kira-mcp

💡 还想匹配文本？ pip install "kira-mcp[ocr]" 可启用 find_element(text="Send")，让 Agent 按标签点击，而不必凭图标判断。

安装选项

上面的快速入门使用了 pip。如需进行隔离的全局安装，且不影响任何项目的 site-packages：

pipx install kira-mcp

这两种形式都会安装 kira-mcp 控制台脚本，并注册所有工具模块。

OmniParser-v2 YOLO 图标检测器权重（icon_detect/model.pt，约 39 MB）已包含在 wheel 中，无需单独下载。服务启动时会从磁盘加载并预热这些权重。

如果你正在开发 kira-mcp 本身？克隆仓库并以可编辑模式安装：git clone https://github.com/Anmol202005/kira-mcp.git && cd kira-mcp && pip install -e .

如果你的克隆缺少权重（例如浅克隆，或你已将其删除），请通过以下方式恢复：

hf download microsoft/OmniParser-v2.0 \
  icon_detect/model.pt \
  icon_detect/model.yaml \
  --local-dir src/kira_mcp/weights

或者，在环境中设置 KIRA_YOLO_WEIGHTS，指向磁盘上其他位置的 model.pt。

其他 Agent 宿主

快速入门介绍了 Claude Desktop。其他所有宿主都使用相同的配置格式——将其指向 kira-mcp 命令：

• Claude Code — claude mcp add kira-mcp -- kira-mcp
• Cursor / Cline / Continue / Windsurf — 在宿主的 MCP 配置中添加相同的 mcpServers 代码块。

不想依赖已安装的脚本？在任何需要命令的位置都可以使用模块形式：

{ "command": "python", "args": ["-m", "kira_mcp"] }

编辑配置后，重启宿主。所有工具都会显示在 kira-mcp 命名空间下。

工具

视觉

鼠标

键盘

按键名称可使用 pyautogui.KEYBOARD_KEYS 中的任意值，以及常见别名（ctrl、alt、shift、cmd/command、win/windows/super、meta、esc/escape、enter/return、space/spacebar、pgup/pageup、pgdn/pagedown、del、ins）。

屏幕

剪贴板

典型 Agent 循环

perceive_screen()                             # → annotated JPEG inline + JSON: {width, height, elements: [{id, bbox, cx, cy, confidence}, …]}
# agent picks an element by id, reads its (cx, cy) — already in absolute screen pixels
mouse_click(x=cx, y=cy)
perceive_screen()                             # verify the action landed

用一个工具观察，用一个工具操作，重复直到完成。

目录结构

src/kira_mcp/
├── __main__.py        # entry — `python -m kira_mcp` or `kira-mcp`
├── _mcp.py            # shared FastMCP instance + system instructions
├── lib/
│   ├── keys.py        # key-name normalization for pyautogui
│   ├── cache.py       # screenshot + per-element OCR hash cache
│   └── ocr.py         # optional OCR backend shim
└── tools/
    ├── __init__.py    # side-effect imports → registers tools
    ├── parse.py       # `perceive_screen` — screenshot + local YOLO icon-detector
    ├── screen.py      # `screen_size` + the `Region` model
    ├── mouse.py
    ├── keyboard.py
    └── clipboard.py

要添加新工具，请编写一个使用 @mcp.tool() 装饰的函数（从 kira_mcp._mcp 导入），并在 tools/__init__.py 中导入该模块。

本地开发

pip install -e .
python -m kira_mcp        # stdio server — drive it from your MCP host

安全

启动时会启用 pyautogui.FAILSAFE——将鼠标猛移到左上角会引发 FailSafeException，并中止 Agent 正在执行的操作。请保持启用状态。 服务明确不会通过工具调用提供禁用它的方式。

Wayland 说明

在 Linux Wayland 会话中，原始 X11 屏幕截图会返回黑色缓冲区。GNOME Wayland 还会阻止未提权的调用方以编程方式截图。如果 perceive_screen 返回黑色图像（或完全没有检测结果），请登录 X11 会话，或切换到附带 wlr-screencopy 的 Wayland 合成器（Hyprland、Sway、river、Niri）或 KDE Plasma 会话。

许可证

MIT — 参见 LICENSE。