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):
- An MCP Host (like an AI assistant running in WSL) calls the
save_screenshot_to_host_workspacetool, providing its WSL workspace path as an argument. - This server (running on Windows) captures the screen.
- The server converts the received WSL path to a Windows-accessible UNC path (e.g.,
\\wsl$\Distro\path). - The server saves the screenshot to the specified location within the Host's WSL filesystem via the UNC path.
- The server returns
"success"or"failed:...". - The MCP Host knows the file is saved in its workspace (or a sub-directory if specified in the path argument).
- The MCP Host can then pass the WSL path to another specialized MCP server (running in WSL) for image analysis.
Alternative Workflow (General):
- MCP Host calls
take_screenshot_and_return_path, optionally specifying a filename. - Server saves the screenshot to its local
images/directory. - Server returns the absolute path (e.g., Windows path) to the saved file.
- 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 toworkspace_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 tolatest_screenshot.jpg.
- Returns:
str- Absolute path or"failed: [error message]".
- Use Case: Saves a screenshot to a fixed
-
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 toscreenshot.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 syncmcp[cli]>=1.4.1,pyautogui, andPillow.
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:
-
Project Location: Place this
screenshot-serverproject folder on your Windows filesystem (e.g.,C:\Users\YourUser\projects\screenshot-server). -
Windows Dependencies: Install Python,
uv, and project dependencies (uv sync ...) directly on Windows within the project folder. -
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)
- AI Assistant identifies its current workspace path (e.g.,
/home/user/current_project). - AI Assistant uses
use_mcp_toolto callsave_screenshot_to_host_workspaceonScreenshot-server, passinghost_workspace_path="/home/user/current_project"and optionally aname. - Receives
"success". - AI Assistant knows the screenshot is now at
/home/user/current_project/workspace_screenshot.jpg(or the specified name). - AI Assistant uses
use_mcp_toolto call an image analysis server/tool (also running in WSL), passing the WSL path/home/user/current_project/workspace_screenshot.jpg. - 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 foruv.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 fortake_screenshot_and_return_path.