Screenshot MCP Server

截图服务器（文件路径集中）

该项目提供了一个 MCP（模块化通信协议）服务器，旨在捕获屏幕截图并方便其他进程或 AI 助手使用，主要通过将屏幕截图保存到客户端（主机）指定的文件路径来实现。

核心问题与解决方案

测试证明，直接解读 AI 助手通过 MCP 发送的截图图像数据并不可靠。此服务器采用了更稳健的工作流程，专注于文件路径：

推荐的工作流程（WSL 主机 -> Windows Server）：

1. MCP 主机（类似于在 WSL 中运行的 AI 助手）调用save_screenshot_to_host_workspace工具，并提供其WSL 工作区路径作为参数。
2. 该服务器（在 Windows 上运行）捕获屏幕。
3. 服务器将接收到的 WSL 路径转换为 Windows 可访问的 UNC 路径（例如， \\wsl$\Distro\path ）。
4. 服务器通过 UNC 路径将屏幕截图保存到主机的 WSL 文件系统内的指定位置。
5. 服务器返回"success"或"failed:..." 。
6. MCP 主机知道该文件保存在其工作区中（或如果在路径参数中指定，则保存在子目录中）。
7. 然后，MCP 主机可以将WSL 路径传递到另一个专门的 MCP 服务器（在 WSL 中运行）进行图像分析。

替代工作流程（常规）：

1. MCP Host 调用take_screenshot_and_return_path ，可选择指定文件名。
2. 服务器将屏幕截图保存到其本地images/目录。
3. 服务器返回已保存文件的绝对路径（例如 Windows 路径）。
4. MCP 主机接收路径并将其（可能带有转换）传递给分析服务器。

可用工具

该服务器提供以下工具，按推荐用途排序：

• save_screenshot_to_host_workspace(host_workspace_path: str, name: str = "workspace_screenshot.jpg")
  • **推荐使用：**将屏幕截图直接保存到 AI 助手（主机）当前的 WSL 工作区。这是实现无缝集成的首选方法。
  • **操作：**截取屏幕截图，将提供的 WSL 路径转换为 UNC 路径，并将文件保存到主机的工作区。自动检测 WSL 发行版名称。
  • 参数：
    • host_workspace_path (str)：主机工作区的绝对 WSL 路径（例如， /home/user/project ）。
    • name （ str ，可选）：文件名。默认为workspace_screenshot.jpg 。
  • 返回： str - "success"或"failed: [error message]" 。
• take_screenshot_and_return_path(name: str = "latest_screenshot.jpg")
  • **用例：**将屏幕截图保存到相对于服务器位置的固定images/目录，并返回绝对路径（通常是 Windows 路径）。当调用者需要该路径进行外部处理时，此功能非常有用。
  • 参数：
    • name （ str ，可选）：文件名。默认为latest_screenshot.jpg 。
  • 返回： str - 绝对路径或"failed: [error message]" 。
• take_screenshot_path(path: str = "./", name: str = "screenshot.jpg")
  • **用例：**将屏幕截图保存到 Windows 路径或 UNC 路径指定的任意位置（例如，保存在主机工作区之外）。需要调用者仔细指定路径。
  • 参数：
    • path (str, 可选): 目标目录（Windows 或 UNC 路径）。默认为服务器的工作目录。
    • name （ str ，可选）：文件名。默认为screenshot.jpg 。
  • 返回： str - "success"或"failed: [error message]" 。

设置和使用

1. 先决条件

• **Python 3.x：**服务器运行的机器上必需。
• **依赖项：**使用uv安装：
  uv sync
  所需库包括mcp[cli]>=1.4.1 、 pyautogui和Pillow 。

2.运行服务器

该服务器通常由MCP 主机根据其配置启动。

3. 环境考虑（特别是 WSL2）

关键点：要捕获Windows 屏幕，此screenshot.py服务器必须直接在 Windows 上运行。

推荐的 WSL2 主机 -> Windows Server 设置：

1. 项目位置：将此screenshot-server项目文件夹放在您的Windows 文件系统上（例如， C:\Users\YourUser\projects\screenshot-server ）。
2. Windows 依赖项：在Windows的项目文件夹中直接安装 Python、 uv和项目依赖项（ uv sync ... ）。
3. **MCP 主机配置（在 WSL 中）：**配置您的 MCP 主机（在 WSL 中运行），以便使用 PowerShell 在 Windows 上启动服务器。更新mcp_settings.json （或等效文件）：
   { "mcpServers": { "Screenshot-server": { "command": "powershell.exe", "args": [ "-Command", "Invoke-Command -ScriptBlock { cd '<YOUR_WINDOWS_PROJECT_PATH>'; & '<YOUR_WINDOWS_UV_PATH>' run screenshot.py }" ] } // ... other servers ... } }
   • 用您的实际 Windows 路径替换路径。

4. 工作流示例（WSL 中的 AI 助手）

1. AI Assistant 识别其当前工作区路径（例如， /home/user/current_project ）。
2. AI Assistant 使用use_mcp_tool在Screenshot-server上调用save_screenshot_to_host_workspace ，并传递host_workspace_path="/home/user/current_project"以及可选的name 。
3. 收到"success" 。
4. AI Assistant 知道屏幕截图现在位于/home/user/current_project/workspace_screenshot.jpg （或指定的名称）。
5. AI Assistant 使用use_mcp_tool调用图像分析服务器/工具（也在 WSL 中运行），传递 WSL 路径/home/user/current_project/workspace_screenshot.jpg 。
6. 图像分析服务器读取文件并执行其任务。

文件结构

• screenshot.py ：核心 MCP 服务器脚本。
• README.md ：此文档文件。
• pyproject.toml ： uv的项目定义和依赖项。
• uv.lock ：依赖锁文件。
• .gitignore ：Git 忽略配置。
• .python-version ：（可选）Python 版本说明符。
• server.log ：服务器生成的日志文件。
• images/ ： take_screenshot_and_return_path的默认目录。