Winsight MCP

🚀 WinSight MCP

WinSight MCP 是一個 Windows 屏幕捕獲 MCP 服務器，它能讓 Claude Code 對 Windows 桌面進行屏幕捕獲、窗口管理和應用程序啟動操作。

🚀 快速開始

選項 1：uvx（推薦）

無需安裝，可直接運行：

{
  "mcpServers": {
    "winsight": {
      "command": "uvx",
      "args": ["winsight-mcp"]
    }
  }
}

將上述內容添加到項目的 .mcp.json 或 ~/.claude/claude_desktop_config.json 文件中。

選項 2：使用 pip 安裝

pip install winsight-mcp

然後進行配置：

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

選項 3：從源代碼安裝

git clone https://github.com/TheoEwzZer/WinSight-MCP.git
cd WinSight-MCP
uv sync

{
  "mcpServers": {
    "winsight": {
      "command": "uv",
      "args": ["--directory", "/path/to/WinSight-MCP", "run", "winsight-mcp"]
    }
  }
}

✨ 主要特性

• 屏幕截圖：可對整個屏幕、特定區域或特定窗口進行截圖。
• 窗口捕獲：使用 Win32 PrintWindow API，即使窗口被其他窗口遮擋，也能捕獲其真實內容。
• 列出並檢查：可列出並檢查打開的窗口和顯示器信息（標題、位置、大小、狀態、分辨率）。
• 窗口控制：可對窗口進行移動、調整大小、最小化、最大化、恢復和聚焦等操作。
• 應用程序啟動：可啟動應用程序並等待其窗口出現。

📦 安裝指南

系統要求

• Windows 10/11
• Python 3.10+

💻 使用示例

MCP 服務器連接成功後，你可以向 Claude Code 提出類似以下的請求：

• "對我的屏幕進行截圖"
• "列出所有打開的窗口"
• "捕獲記事本窗口"
• "打開計算器並對其進行截圖"
• "聚焦 Chrome 窗口"
• "將應用窗口調整為 800x600 大小並進行截圖"
• "將窗口移動到左上角"
• "我有哪些顯示器？"

📚 詳細文檔

工具說明

截圖工具

窗口管理工具

系統工具

🔧 技術細節

測試相關

項目共有 112 個測試用例，覆蓋了所有模塊。測試使用 Win32 API 的模擬對象，因此可以在任何平臺上運行。

運行測試

uv run pytest

測試結構

tests/
  conftest.py              # 共享的測試夾具和 Win32 存根
  test_types.py            # TypedDict 定義驗證
  test_screenshot.py       # 屏幕/區域/窗口捕獲測試（mss, Win32 DC）
  test_window_manager.py   # 窗口列表、查找、聚焦、調整大小、移動、最小化/最大化/恢復測試
  test_process_manager.py  # 應用程序啟動和窗口輪詢測試
  test_server.py           # MCP 工具註冊和集成測試

添加測試

1. 將新的測試用例放在對應的 test_<module>.py 文件中。
2. 使用 conftest.py 中的共享測試夾具（sample_window_info, mcp_server, fake_png_bytes）。
3. 使用 @patch("winsight_mcp.<module>.win32gui") 模擬 Win32 API，測試中切勿調用真實的 Win32 函數。
4. 對於服務器集成測試，使用 _call 輔助函數調用工具，使用 _text 提取字符串結果。

📄 許可證

本項目採用 MIT 許可證。