mcp-screenshot

The MCP Screenshot Server exposes a FastAPI-based REST API that lets automated agents capture screenshots from a Windows environment. It supports full-screen captures, window-specific captures by title, and region-based captures defined as coordinates [x, y, width, height]. Clients can request either binary PNG data or a base64-encoded image, making it easy to integrate with LLMs or orchestration tools that rely on text-based payloads.

To use it, run the server using your preferred Python environment. Once running, send POST requests to the /screenshot endpoint with a JSON body specifying the capture parameters. For example, to grab a full-screen screenshot, omit region and window_title; to capture a specific window, provide window_title; to capture a region, provide region with coordinates. The API follows the MCP pattern so you can feed the image data directly into your agent workflow, log it, or pass it to other services for analysis or visualization.

Prerequisites:

• Python 3.11+ installed on Windows (the target platform for this server)
• Internet access to install dependencies

Installation steps:

1. Clone the repository:

git clone https://github.com/yourusername/mcp-screenshot-server.git
cd mcp-screenshot-server

2. Create and activate a virtual environment:

python -m venv .venv
# Windows
.\.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Run the server (development mode):

uvicorn main:app --reload

5. Optional: run with a production-oriented ASGI server and proper host/port configuration as needed.

• The server is Windows-focused in this implementation. Cross-platform tweaks may be required for macOS/Linux environments.
• Dependencies include mss/pyautogui for screenshots and pygetwindow for optional window matching. Ensure you have the necessary permissions to capture the screen in your OS.
• If you encounter headless or restricted-screen issues, verify that the process has access to the display and that any required desktop interaction permissions are granted.
• The API supports both base64-encoded and binary PNG outputs. Use base64 when embedding images in JSON-based MCP flows; otherwise, request the binary mode as appropriate by your client implementation.
• For MCP interoperability, send and receive data in the MCP-compliant structure described in your integration layer; the endpoint returns a JSON envelope with status, mode, and image data.