desktop-mcp

Linux（Waylandを含む）上のLLM向けデスクトップビジョン＆コントロール — モデルが 画面全体のスクリーンショットを取得し、表示されているものに対してクリック、タイプ、スクロールを 実行します。stdio上のプレーンなMCPなので、Claude Code、Claude Desktop、Cursor、 その他のMCPクライアントで動作します。

最初にお読みください：これは不要かもしれません

Anthropicはコンピューター操作をネイティブに提供しており、それが機能する環境では そちらを使うべきです — 統合度が高く、実際にメンテナンスされています：

• macOSおよびWindows：Claude Desktopにはコンピューター操作が組み込まれており、Coworkおよび Claude Codeで利用できます。実際のデスクトップを操作します。 （ドキュメント）

• 独自エージェントの構築：Claude APIにはファーストパーティのcomputerツールがあります （GA版はcomputer_toolset_20260801ツールセット）。 （ドキュメント）

このツールが埋めるギャップはLinuxです。 2026年8月現在、コンピューター操作は Linuxデスクトップアプリでは利用できず、Waylandでのデスクトップ自動化は X11ではなかった形で困難を極めます：

• COSMICのコンポジタはwlr-screencopyを実装していないため、grimは失敗し、 スクリーンショットツールはすべてコンポジタごとの個別対応が必要になります。

• カーソル位置を問い合わせるプロトコルも、他のクライアントのウィンドウを列挙するプロトコルも 存在しません。

• 入力はコンポジタの下層、/dev/uinput経由で行う必要があります。なぜなら、 一般的にパッケージされているydotoolは相対ポインタしか公開しておらず、 長距離のジャンプがポインタ加速によって変形してしまうからです。

macOSやWindowsをお使いなら、このリポジトリはほぼ不要です。Linux、 特にWaylandをお使いなら、これが有効な選択肢です。

Related MCP server: mcp-linux-desktop

ステータス

クロスプラットフォーム対応として書かれていますが、実際に検証されているのは 1つの構成のみです。それ以外はコードパス上の実装であり、実証済みではありません — そのつもりで 扱ってください。

テスト内容と方法

エンドツーエンドで検証済み：

• Pop!_OS 24.04 LTS、カーネル7.0.11、COSMIC（cosmic-comp 1.0.0）、 Wayland、シングル2560x1440ディスプレイ、Python 3.13。

結果：

未検証で知っておくべきこと：マルチモニタレイアウト、HiDPIスケーリング、非US キーボードレイアウト（生のキーコードパスの場合 — wtypeはこれらを正しく処理しますが、 uinputキーコードはUS配列を前提としています）、およびCOSMIC以外のすべてのコンポジタ。

他のプラットフォームからの報告は歓迎します — desktop_infoはバックエンドの問題を 診断するために必要な情報をすべて出力します。

インストール

git clone <this repo> && cd desktop-mcp
uv venv && uv pip install -e .

macOS、Windows、Linux/X11でも入力依存関係が必要です：

uv pip install -e ".[gui]"

Linux：1回限りの権限設定

Waylandで入力を注入するには/dev/uinputへの書き込みが必要ですが、これはデフォルトでは root所有です：

bash scripts/setup-linux.sh   # needs sudo once
# then log out and back in

macOS：1回限りの権限設定

サーバーを起動するアプリ（ターミナル、iTerm、Claude Desktop）に対して、 システム設定 → プライバシーとセキュリティで画面収録とアクセシビリティを 許可してください。

配線

Claude Code：

claude mcp add desktop -- /absolute/path/to/desktop-mcp/.venv/bin/python -m desktop_mcp.server

Claude Desktop（claude_desktop_config.json）とCursor （.cursor/mcp.json）も同じ形式です：

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/desktop-mcp/.venv/bin/python",
      "args": ["-m", "desktop_mcp.server"]
    }
  }
}

ツール

座標

スクリーンショットは送信前に縮小されます（デフォルトでは長辺1400px）。そのため モデルは画像ピクセル単位で作業し、サーバーが毎回の呼び出しでそれらを画面ピクセルに マッピングします。スクリーンショットから読み取った座標をそのまま渡してください。

これは自作のコンピューター操作ツールのほとんどが間違える詳細です。これを間違えると、 すべてのクリックが意図した場所から一定の割合でずれた位置に着地します。

Linuxでydotoolではなく/dev/uinputを使う理由

一般的にパッケージされているydotoolビルドは相対ポインタしか公開していないため、 (1280, 720)へのジャンプは1回の大きな相対移動として配信され、コンポジタが ポインタ加速を適用します。その結果、カーソルはターゲットの近くには着地しますが、 距離が大きいほど誤差も大きくなります。絶対座標のuinputデバイスは加速を回避します： 2560x1440画面で測定した結果、5/5正確でした。ydotoolは/dev/uinputに 書き込めない場合のフォールバックとして残されています。

クリックのタイミング

コンポジタはポインタ移動を非同期でディスパッチするため、ツールキットは カーソルをウィジェット上に置いた移動イベントを処理する前にボタン押下が届くと、 それを無視します。COSMICで測定した結果：移動と押下の間隔が30msだと、ボタンは ハイライトされるだけでアクティベートされません — ホバー状態は座標が正しいことの 証明ですが、この失敗はターゲティングバグと誤読されがちです。250msあればアクティベートされます。 また、押下は約90ms保持しないと、単なるイベントとして扱われず実際のクリックとして 認識されません。

両方の遅延は調整可能ですが、デスクトップが許容する場合にのみ下げてください。

安全性

これによりモデルは、その場に座っている人間と同じ範囲でマシンを操作できるようになります。 画面上のあらゆるもの — 開いているパスワードマネージャー、プライベートメッセージ、 トークン — を読み取ることができ、破壊的なボタンも含めて何でもクリックできます。 セッションは、誰かにキーボードを預けたのと同じように扱ってください。

環境変数：

ctrl+alt+F1〜F12は常にブロックされます。VT切り替えによってグラフィカル セッションが足元から消える可能性があります。

読み取り専用のレビューア用セットアップ：

DESKTOP_MCP_READ_ONLY=1 python -m desktop_mcp.server

検証

.venv/bin/python scripts/mcp_smoke.py   # real stdio MCP round trip