winsight

WinSight MCP

mcp-name: io.github.TheoEwzZer/winsight

Windows 屏幕捕获 MCP 服务——让 Claude Code 看见你的 Windows 桌面。

WinSight 是一个 MCP 服务，可让 Claude Code 在 Windows 上捕获屏幕、管理窗口并启动应用程序。

功能

• 屏幕截图：捕获整个屏幕、指定区域或特定窗口
• 窗口捕获：使用 Win32 PrintWindow API，即使窗口位于其他窗口后方，也能捕获其实际内容
• 列出并检查：打开的窗口和显示器（标题、位置、大小、状态、分辨率）
• 控制窗口——移动、调整大小、最小化、最大化、还原和聚焦
• 启动应用程序并等待其窗口出现

要求

• Windows 10/11
• Python 3.10+

快速开始

选项 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"]
    }
  }
}

工具

屏幕截图

工具	描述
take_screenshot	捕获整个屏幕或指定显示器
screenshot_window	根据标题捕获特定窗口（即使窗口位于其他窗口后方也有效）
screenshot_region	捕获屏幕的矩形区域

窗口管理

工具	描述
list_windows	列出所有可见窗口，并可按标题筛选
get_window_info	获取窗口的详细信息（位置、大小、状态）
focus_window	将窗口置于前台
resize_window	将窗口调整为指定尺寸
move_window	将窗口移动到指定位置
minimize_window	将窗口最小化到任务栏
maximize_window	将窗口最大化以填满屏幕
restore_window	将最小化或最大化的窗口还原到正常状态
wait_for_window	等待窗口出现（带超时的自适应轮询）

系统

工具	描述
list_monitors	列出所有显示器及其分辨率、位置和主显示器标记
open_application	启动应用程序，并可选择等待其窗口出现

示例

连接 MCP 服务后，你可以向 Claude Code 提出以下请求：

• “截取我的屏幕”
• “列出所有打开的窗口”
• “捕获记事本窗口”
• “打开计算器并截取它的屏幕”
• “将 Chrome 窗口置于前台”
• “将应用窗口调整为 800x600 并截屏”
• “将窗口移到左上角”
• “我有哪些显示器？”

测试

该项目包含 112 个测试，覆盖所有模块。测试使用 Win32 API 模拟，因此可在任何平台上运行。

运行测试

uv run pytest

测试结构

tests/
  conftest.py              # Shared fixtures and Win32 stubs
  test_types.py            # TypedDict definitions validation
  test_screenshot.py       # Screen/region/window capture (mss, Win32 DC)
  test_window_manager.py   # Window listing, find, focus, resize, move, min/max/restore
  test_process_manager.py  # Application launch and window polling
  test_server.py           # MCP tool registration and integration

添加测试

1. 将新测试放入对应的 test_<module>.py 文件中
2. 使用 conftest.py 中的共享 fixture（sample_window_info、mcp_server、fake_png_bytes）
3. 使用 @patch("winsight_mcp.<module>.win32gui") 模拟 Win32 API——测试中绝不要调用真实的 Win32 函数
4. 对于服务集成测试，使用 _call 助手调用工具，使用 _text 提取字符串结果

许可证

MIT