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 许可证。