MCP 服务器

windows-mcp-lite

A lightweight Windows automation MCP server that scopes UI operations to a single target window, offering tools like ReadWindow, PeekWindow, Click, Type, Scroll, Screenshot, and App management with reduced token usage compared to full-desktop alternatives.

README

windows-mcp-lite

windows-mcp はWindows操作用のMCPサーバーとして強力ですが、Snapshotのようなツールは常にデスクトップ全体（タスクバー・背面の全ウィンドウ含む）を走査するため、AIエージェントが消費するトークン量が大きくなりがちです。

windows-mcp-liteはこの課題に絞った軽量な代替です。対象ウィンドウ1つだけをスコープにし、コンパクトなテキスト形式で返すことで、同じ情報をより少ないトークンで提供します。

実測値

同じ電卓アプリのウィンドウに対して、実際に稼働中の両サーバーへ問い合わせて比較しました。

	文字数
windows-mcp `Snapshot`（デスクトップ全体）	5630文字
windows-mcp-lite `ReadWindow`（電卓のみ）	678文字
削減率	88.0%

生の比較データは docs/note-assets を参照してください。

提供ツール

観測系

ReadWindow — 対象ウィンドウのUIツリーをコンパクトなテキストで取得
PeekWindow — ウィンドウの存在確認、または特定テキストの有無だけを真偽値で取得（ReadWindowより軽量）
LocateElement — 名前などから要素を検索し座標を取得
Screenshot — スクリーンショットを取得

操作系

Click / Type / Scroll / Move — 座標を指定して操作（ReadWindow/LocateElementで得た座標を使う）
Shortcut — キーボードショートカット送信
App — アプリの起動（スタートメニュー名 or 実行ファイルパス指定）・切替・リサイズ

windows-mcpのSnapshotが返す数値ラベル（前回スナップショット参照用）は保持しないため、操作系ツールには常に明示的な[x, y]座標を渡します。

インストール

pyproject.tomlでwindows-mcpをpinned依存として利用しています（Python 3.12+、Windows専用）。

uv sync

MCPクライアント（Claude Code等）の設定例:

{
  "mcpServers": {
    "windows-mcp-lite": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "<このリポジトリのパス>", "windows-mcp-lite"]
    }
  }
}

既知の制約

電卓アプリの計算結果表示欄はUI Automationツリーに現れません（windows-mcp本体でも同様の制約）。
モーダルダイアログを伴うウィンドウで、かつそのウィンドウがフォアグラウンドでもない場合は、windows-mcp本体・lite共通の制約として検出できないことがあります（詳細は PLAN.md を参照）。

アーキテクチャ

UI Automation/COM連携を再実装せず、windows-mcpの内部クラス（Desktop/Tree等）をライブラリとして直接importしています。非公開の内部APIに依存する形になるため、windows-mcp側のアップデートで壊れる可能性があります。設計判断や実測の詳細な経緯は PLAN.md にまとめています。