Screenshot Server (File Path Focused)

This project provides an MCP (Modular Communication Protocol) server designed to capture screenshots and facilitate their use by other processes or AI assistants, primarily by saving the screenshot to a file path specified by the client (Host).

Core Problem & Solution

Directly interpreting screenshot image data sent via MCP by AI assistants proved unreliable in testing. This server adopts more robust workflows focused on file paths:

Recommended Workflow (WSL Host -> Windows Server):

1. An MCP Host (like an AI assistant running in WSL) calls the save_screenshot_to_host_workspace tool, providing its WSL workspace path as an argument.
2. This server (running on Windows) captures the screen.
3. The server converts the received WSL path to a Windows-accessible UNC path (e.g., \wsl$Distropath).
4. The server saves the screenshot to the specified location within the Host’s WSL filesystem via the UNC path.
5. The server returns "success" or "failed:...".
6. The MCP Host knows the file is saved in its workspace (or a sub-directory if specified in the path argument).
7. The MCP Host can then pass the WSL path to another specialized MCP server (running in WSL) for image analysis.

Alternative Workflow (General):

1. MCP Host calls take_screenshot_and_return_path, optionally specifying a filename.
2. Server saves the screenshot to its local images/ directory.
3. Server returns the absolute path (e.g., Windows path) to the saved file.
4. MCP Host receives the path and passes it (with potential conversion) to an analysis server.

Available Tools

This server provides the following tools, ordered by recommended usage:

• save_screenshot_to_host_workspace(host_workspace_path: str, name: str = "workspace_screenshot.jpg")

  • Recommended Use: Saves a screenshot directly into the AI Assistant’s (Host’s) current WSL workspace. This is the preferred method for seamless integration.
  • Action: Takes a screenshot, converts the provided WSL path to a UNC path, and saves the file to the Host’s workspace. Automatically detects the WSL distribution name.
  • Args:
    • host_workspace_path (str): The absolute WSL path of the Host’s workspace (e.g., /home/user/project).
    • name (str, optional): Filename. Defaults to workspace_screenshot.jpg.
  • Returns: str - "success" or "failed: [error message]".

• take_screenshot_and_return_path(name: str = "latest_screenshot.jpg")

  • Use Case: Saves a screenshot to a fixed images/ directory relative to the server’s location and returns the absolute path (typically a Windows path). Useful if the caller needs the path for external processing.
  • Args:
    • name (str, optional): Filename. Defaults to latest_screenshot.jpg.
  • Returns: str - Absolute path or "failed: [error message]".

• take_screenshot_path(path: str = "./", name: str = "screenshot.jpg")

  • Use Case: Saves a screenshot to an arbitrary location specified by a Windows path or a UNC path (e.g., for saving outside the Host’s workspace). Requires careful path specification by the caller.
  • Args:
    • path (str, optional): Target directory (Windows or UNC path). Defaults to server’s working directory.
    • name (str, optional): Filename. Defaults to screenshot.jpg.
  • Returns: str - "success" or "failed: [error message]".

Setup and Usage

1. Prerequisites

• Python 3.x: Required on the machine where the server will run.
• Dependencies: Install using uv:

  uv sync
  

  Required libraries include mcp[cli]>=1.4.1, pyautogui, and Pillow.

2. Running the Server

This server is typically launched by an MCP Host based on its configuration.

3. Environment Considerations (Especially WSL2)

Crucial Point: To capture the Windows screen, this screenshot.py server must run directly on Windows.

Recommended WSL2 Host -> Windows Server Setup:

1. Project Location: Place this screenshot-server project folder on your Windows filesystem (e.g., C:UsersYourUserprojectsscreenshot-server).

2. Windows Dependencies: Install Python, uv, and project dependencies (uv sync ...) directly on Windows within the project folder.

3. MCP Host Configuration (in WSL): Configure your MCP Host (running in WSL) to launch the server on Windows using PowerShell. Update mcp_settings.json (or equivalent):

   {
     "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 ...
     }
   }
   

   • Replace paths with your actual Windows paths.

4. Workflow Example (AI Assistant in WSL)

1. AI Assistant identifies its current workspace path (e.g., /home/user/current_project).
2. AI Assistant uses use_mcp_tool to call save_screenshot_to_host_workspace on Screenshot-server, passing host_workspace_path="/home/user/current_project" and optionally a name.
3. Receives "success".
4. AI Assistant knows the screenshot is now at /home/user/current_project/workspace_screenshot.jpg (or the specified name).
5. AI Assistant uses use_mcp_tool to call an image analysis server/tool (also running in WSL), passing the WSL path /home/user/current_project/workspace_screenshot.jpg.
6. The image analysis server reads the file and performs its task.

File Structure

• screenshot.py: The core MCP server script.
• README.md: This documentation file.
• pyproject.toml: Project definition and dependencies for uv.
• uv.lock: Dependency lock file.
• .gitignore: Git ignore configuration.
• .python-version: (Optional) Python version specifier.
• server.log: Log file generated by the server.
• images/: Default directory for take_screenshot_and_return_path.