Kira Mcp

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

kira-mcp は、MCP 対応のエージェントホスト（Claude Desktop、Claude Code、Cursor、Cline、Continue など）に、ホストマシン上でのコンピューター操作機能を提供するローカルの Model Context Protocol サーバーです。

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

Kira が CAPTCHA を最初から最後まで解決します。perceive_screen を 1 回実行するだけで、クリック可能なピクセル座標を取得でき、人間が介入する必要はありません。

Windows 向けに構築・調整されています。macOS と Linux はベストエフォート対応です。ほとんどのツールは動作しますが、一部の UI の慣習が異なります。

• ビジョン — perceive_screen は、画面を一度だけ確認するためのエージェント向けツールです。現在の画面をメモリ上に取り込み、ローカルの microsoft/OmniParser-v2 YOLO アイコン検出器で解析し、注釈付き画像と、各要素の {id, bbox, cx, cy, confidence} を含む JSON を返します。座標は画面上の絶対ピクセル値なので、エージェントは cx, cy をそのまま mouse_click に渡せます。API キーもネットワーク呼び出しも不要です。
• デスクトップの自動化 — pyautogui、mss、pyperclip を使用した、ピクセル単位で正確なマウス操作、キーボード入力（キーの組み合わせやキーの長押しを含む）、クリップボードの読み取り・書き込みに対応しています。

このサーバーは stdio JSON-RPC を使用し、エージェントホストによって子プロセスとして起動されます。

クイックスタート

Python 3.10+ と MCP ホストが必要です（以下の例では Claude Desktop を使用します）。お使いの OS を選択してください。

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") が有効になり、アイコンを目で探す代わりに、ラベルを指定してエージェントがクリックできるようになります。

インストール方法

上記のクイックスタートでは 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 を指定してください。

その他のエージェントホスト

クイックスタートでは 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）を使用できます。

画面

クリップボード

一般的なエージェントのループ

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

見るためのツールを1つ、操作するためのツールを1つ使い、完了するまで繰り返します。

構成

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 が発生し、エージェントが実行中の処理が中断されます。有効のままにしてください。 サーバーでは、ツール呼び出しからこれを無効にする方法を明示的に提供していません。

Wayland に関する注意

Linux の Wayland セッションでは、X11 の生の画面キャプチャは黒いバッファーを返します。GNOME Wayland ではさらに、権限のない呼び出し元によるプログラムからのスクリーンショット取得がブロックされます。perceive_screen が黒い画像を返す場合（または検出結果がまったくない場合）は、X11 セッションにログインするか、wlr-screencopy を搭載した Wayland コンポジター（Hyprland、Sway、river、Niri）または KDE Plasma セッションに切り替えてください。

ライセンス

MIT — LICENSE を参照してください。