Mcp Window Screenshooter

Window Screenshooter MCP Server 🖼️

一个跨平台的 Model Context Protocol（MCP）服务，让 AI Agent 能够截取指定应用窗口的屏幕截图！（≧◡≦）

概览

Window Screenshooter 是一个用 Python 构建的 MCP 服务，为 AI Agent 提供在 Windows 和 Linux 平台上截取指定应用窗口屏幕截图的能力。与只能截取整个屏幕的传统屏幕捕获解决方案不同，此服务支持精准地按窗口捕获，适用于 AI 验证工作流、自动化测试和应用监控。

✨ 新功能：智能窗口状态恢复与焦点管理！

最新版本现已支持自动恢复窗口状态和智能焦点处理！🎉

截取窗口时，服务会：

• 📸 保存窗口的原始状态（最小化、最大化、位置等）
• 🔄 根据需要临时调整窗口以便截取
• ✨ 截取完成后将窗口恢复到完全相同的原始状态
• 🎯 自动检测你的编辑器（Cursor、Trae、Windsurf、VS Code 等），并将焦点恢复到编辑器
• 📉 如果找不到调用应用，则最小化已截取的窗口
• 💫 在所有受支持的平台上无缝运行

这样一来，你的工作流将保持顺畅——焦点会返回到编辑器，窗口也不会停留在意外状态！

主要功能

• 🖼️ 指定窗口捕获：按名称或标题指定单个应用窗口
• 🌐 跨平台支持：适用于 Windows 和 Linux，并采用针对平台优化的后端
• 🔧 MCP 集成：通过 Model Context Protocol 与 AI Agent 无缝集成
• 📡 STDIO 传输：使用标准输入/输出进行可靠通信
• ⚡ 性能优化：针对不同平台的实现，确保最高效率

安装与设置

前提条件

• Python 3.12+
• Windows 或 Linux

快速开始

1. 克隆或下载此存储库：

   git clone <your-repo-url>
   cd window-screenshooter
   

2. 安装依赖项：

   pip install pywinctl pillow pywin32
   # Or use the project file
   pip install -e .
   

3. 测试服务：

   python test-mcp.py
   

4. 运行 MCP 服务：

   # STDIO mode (for MCP clients)
   python server.py
   

MCP 工具

此服务提供三个主要的 MCP 工具：

1. capture_window

按标题或标识符截取指定窗口的屏幕截图。

参数：

• windowTitle（string）：要匹配的完整或部分窗口标题
• outputPath（string，可选）：屏幕截图的保存位置
• format（string，可选）：图像格式（PNG、JPEG）- 默认值：PNG
• quality（int，可选）：JPEG 质量（1-100）- 默认值：85

返回： Base64 编码的图像数据或文件路径确认信息

示例：

# Save to file
await capture_window("Notepad", "screenshot.png", "PNG")

# Get base64 data
await capture_window("Calculator")

2. list_windows

列出系统上所有可用窗口。

返回： 窗口对象数组，包含 ID、标题、位置和尺寸信息

示例：

await list_windows()

3. get_window_info

获取指定窗口的详细信息。

参数：

• windowIdentifier（string）：窗口标题或 ID

返回： 窗口元数据，包括位置、尺寸、可见性状态和进程信息

示例：

await get_window_info("Visual Studio Code")

平台专属功能

Windows 实现

• 使用 win32gui 和 BitBlt API 实现可靠的窗口捕获
• 可捕获最小化、隐藏或被其他窗口遮挡的窗口
• 集成高性能 Graphics Capture API
• 提供 Windows 句柄（HWND）和进程信息

Linux 实现

• 使用基于 X11 的窗口捕获和原生协议
• 直接访问窗口缓冲区，实现高效捕获
• 支持常见的 Linux 桌面环境

MCP 客户端配置

用于 Cursor IDE

将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "window-screenshooter": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/window-screenshooter",
      "transport": "stdio"
    }
  }
}

用于 Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "window-screenshooter": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/window-screenshooter"
    }
  }
}

💡 IDE 配置提示

📝 注意： 为了更好地集成到工作流中，建议将以下规则添加到 IDE 配置中：

“使用 MCP 屏幕截图工具截取窗口或屏幕之前，务必先列出窗口，以获取正确的名称。如果正在处理 Web 项目，默认浏览器是 Brave。如果正在处理 Unity 项目，用户需要的是 Unity 游戏场景窗口。完成截图或屏幕截取后，务必使用视觉功能进行分析。”

这有助于准确定位窗口，并妥善分析截取的内容！✨

使用示例

AI 开发工作流

• 代码验证：AI 截取 Unity 编辑器截图，验证游戏对象的位置
• UI 测试：在自动化测试流程中捕获应用状态
• 文档编写：生成应用界面的可视化文档
• 调试：通过视觉方式确认应用行为的变化

自动化场景

• 质量保证：通过截图比对进行回归测试
• 流程监控：捕获应用状态以验证工作流
• 训练数据：生成带标签的截图，用于计算机视觉训练

错误处理

服务实现了完善的错误处理机制，涵盖：

• 找不到窗口的情况
• 因权限不足而导致的截图尝试失败
• 跨平台兼容性问题
• 无效参数验证
• 平台特定功能不可用时的平稳降级

开发与贡献

项目结构

window-screenshooter/
├── server.py              # Main MCP server implementation
├── windows_capture.py     # Windows-specific capture logic
├── linux_capture.py      # Linux-specific capture logic
├── test-mcp.py           # Test script for functionality
├── mcp-config-example.json # Example MCP configuration
├── pyproject.toml        # Project dependencies
└── README.md            # This file

测试

运行测试脚本以验证功能：

python test-mcp.py

常见问题

1. “找不到窗口”错误：

   • 使用 list_windows 检查准确的窗口标题
   • 尝试使用部分标题进行匹配
   • 确保窗口可见且未最小化

2. Windows 上的权限错误：

   • 必要时以管理员身份运行
   • 检查 Windows 安全设置

3. 导入错误：

   • 确保已安装所有依赖项：pip install pywinctl pillow pywin32
   • 检查 Python 版本（需要 3.12+）

平台兼容性

• Windows：通过原生 Win32 API 提供完整支持
• Linux：通过 X11 集成提供基础支持

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。