JinDaGe - winsight-mcp MCP Details

article

README

🚀 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 大小并进行截图"
"将窗口移动到左上角"
"我有哪些显示器？"

📚 详细文档

工具说明

截图工具

| 工具 | 描述 | | ------------------- | ---------------------------------------------------------------- | | 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 | 启动应用程序，并可选择等待其窗口出现 |

🔧 技术细节

测试相关

项目共有 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 工具注册和集成测试

添加测试

将新的测试用例放在对应的 test_<module>.py 文件中。
使用 conftest.py 中的共享测试夹具（sample_window_info, mcp_server, fake_png_bytes）。
使用 @patch("winsight_mcp.<module>.win32gui") 模拟 Win32 API，测试中切勿调用真实的 Win32 函数。
对于服务器集成测试，使用 _call 辅助函数调用工具，使用 _text 提取字符串结果。

📄 许可证

本项目采用 MIT 许可证。

winsight-mcp