screen-mcp

Omarchy / Hyprland Wayland デスクトップに AI エージェントの目を与える MCP (Model Context Protocol) サーバーです。grim 経由でスクリーンショットを取得し、Gemini API によるオプションの画像分析を提供します。呼び出し元のモデルにネイティブのビジョンエンコーダーがない場合に便利です。

機能

スクリーンショットは grim (wlroots screencopy プロトコル) を使用します。X11 は不要です。

前提条件

• Omarchy、Hyprland、または wlroots ベースの Wayland コンポジタ

• grim — Wayland スクリーンショットツール

• slurp — (オプション) 対話的な領域選択ヘルパー

• hyprctl — Hyprland ウィンドウ/クエリ CLI

• jq — (オプション) 一部のヘルパースクリプトで使用

確認方法:

grim --help && hyprctl clients -j | head -c 20

画像分析用 (オプション)

• Gemini API キー — https://aistudio.google.com で取得

• 環境変数にエクスポート:

export GEMINI_API_KEY="your-api-key-here"

キーがない場合、スクリーンショットツールは引き続き動作します。analyze_image と screenshot_and_analyze のみエラーを返します。

インストール

Claude Desktop 経由

Claude Desktop の claude_desktop_config.json に次を追加:

{
  "mcpServers": {
    "screen-mcp": {
      "command": "npx",
      "args": ["-y", "screen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

npx 経由

npx -y screen-mcp

# Or install globally:
npm install -g screen-mcp

使用例

画面領域をキャプチャ

screenshot_region(x=100, y=200, width=800, height=600, include_cursor=true)

特定のウィンドウをキャプチャ

まず利用可能なウィンドウを一覧表示してアドレスまたはタイトルを取得:

list_windows()

次にタイトル (部分一致)、アドレス、または "focused" でキャプチャ:

screenshot_window(window="Spotify")
screenshot_window(window="focused")
screenshot_window(window="0x557ba79b4900")

Gemini で画像を分析

analyze_image(
  image_path="/tmp/my-screenshot.png",
  prompt="What applications are visible in this screenshot?",
  model="gemini-2.5-flash"
)

または base64 エンコードされた画像データを直接渡す:

analyze_image(
  image="<base64-encoded-image>",
  prompt="Describe what you see in this image.",
  mime_type="image/png"
)

キャプチャと分析を 1 回で実行

screenshot_and_analyze(
  x=0, y=0, width=1920, height=1080,
  prompt="Count the number of windows open and list their titles.",
  scale=0.5,
  model="gemini-2.5-flash"
)

開発

# Install deps
npm install

# Build
npm run build

# Run
npm start

# Development (recompile on change)
npm run dev

仕組み

• キャプチャ: src/capture.ts は grim (スクリーンショット) と hyprctl (ウィンドウ列挙) をラップします。ウィンドウキャプチャはまず grim -T <stableId> (foreign-toplevel ハンドル) を試し、失敗した場合は grim -g "<x>,<y> <w>x<h>" (hyprctl からのジオメトリ) にフォールバックします。

• 分析: src/gemini.ts は公式の @google/genai SDK を使用します。画像は base64 としてインラインで Gemini API の interactions.create エンドポイントに渡されます。

• サーバー: src/index.ts は @modelcontextprotocol/server を使用して、stdio トランスポートの MCP サーバーとしてすべてを配線します。

ライセンス

MIT