使用说明

项目简介

winshot-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，专注于为大型语言模型（LLM）提供窗口截图功能。通过 winshot-mcp，LLM 客户端可以请求服务器截取指定应用程序窗口的屏幕截图，并以 URI 的形式获取图像数据。这使得 LLM 能够“看到”并理解应用程序的用户界面，从而实现更强大的上下文感知能力，例如与 Cursor 编辑器的集成，让 Agent 模式可以分析屏幕内容。

主要功能点

跨平台窗口列表: 支持 Windows, macOS 和 Linux 系统，能够列出当前系统所有活跃窗口。
窗口截图: 能够捕获指定应用程序窗口的屏幕截图。
MCP 协议: 通过 MCP 协议与 LLM 客户端通信，提供标准的上下文服务接口。
HTTP 文件服务器: 内置轻量级 HTTP 文件服务器，通过 URI 安全高效地传输截图数据，避免 Base64 编码带来的额外开销。
可配置图像参数: 支持配置最大图像尺寸和文件大小，优化性能和内存使用。
临时文件管理: 截图文件保存在临时目录，并具有过期自动清理机制。

安装步骤

安装依赖: 打开终端，进入仓库根目录，运行以下命令安装 Python 依赖：
```
pip install -r requirements.txt
```
平台特定依赖:
- Windows: 运行 'pip install pygetwindow pywin32'
- Linux: 运行 'sudo apt-get install xdotool imagemagick'
- macOS: 首次运行时系统会请求屏幕录制权限，请确保终端或 IDE 获得授权（系统设置 > 隐私与安全性 > 屏幕录制）。

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到 winshot-mcp 服务器。以下是一个示例配置，您可以根据实际情况调整参数：

{
  "serverName": "Winshot MCP Server",
  "command": "python",
  "args": [".", "server"],
  "options": {
    // 服务器端口，默认为 8765
    // "--port": "8765",

    // 文件服务器端口，默认为 8766
    // "--fileserver-port": "8766",

    // 截图最大尺寸（像素），默认为 1920
    // "--max-image-dimension": "1200",

    // 截图最大文件大小（MB），默认为 5MB
    // "--max-file-size-mb": "2",

    // 截图临时文件目录，默认为项目根目录下的 tmp 目录。
    // 如果要与 Cursor 集成，需要设置为 Cursor 可以访问的目录，例如用户目录下的某个文件夹。
    // "--tmp-dir": "/Users/username/cursor-accessible-folder",

    // 截图文件过期时间（分钟），默认为 60 分钟
    // "--file-expiry-minutes": "120"
  }
}

注意：

'command' 和 'args' 指定了启动 winshot-mcp 服务器的命令。请确保 'python' 命令可用，并且当前工作目录是仓库根目录。
'options' 中可以配置服务器的各项参数，根据需要进行调整。
如果与 Cursor 集成，务必配置 '--tmp-dir' 参数，指向 Cursor 可以访问的本地文件夹，以便 Cursor 能够通过 '@file' 语法读取截图。

基本使用方法

启动服务器: 在终端中，进入仓库根目录，运行以下命令启动 MCP 服务器：
```
python . server
```
或
```
python -m server
```
您可以使用 '--port'、'--max-image-dimension' 等参数自定义服务器配置，具体参数请参考仓库 README 文档。
客户端请求: 使用 MCP 客户端（例如配置了 winshot-mcp 服务器的 Cursor 编辑器）向服务器发送请求。
- 列出窗口: 客户端可以调用 'list_windows()' 工具获取当前系统所有窗口的列表。
- 捕获窗口: 客户端可以调用 'capture_window(window_title)' 或 'capture_window(window_index)' 工具，根据窗口标题或索引捕获指定窗口的截图。服务器将返回截图的 URI 和本地文件路径（如果配置了 '--tmp-dir'）。
Cursor 集成示例: 在 Cursor 编辑器的 Agent 模式中，您可以使用以下命令与 winshot-mcp 服务器交互：
- 'list_windows()' - 列出所有可用窗口。
- 'capture_window("Window Title")' - 捕获标题包含 "Window Title" 的窗口截图。
- 'capture_window(window_index)' - 捕获指定索引的窗口截图（索引从 'list_windows()' 获取）。
Cursor 可以使用服务器返回的本地文件路径，通过 '@file' 语法直接查看截图，例如：'@/Users/username/cursor-accessible-folder/window_shot_xxx.png'。

关键词

使用说明

信息