home / mcp / mcp screenshot server

MCP Screenshot Server

Provides a server to capture screenshots and annotate images with versatile tools for automation and integration.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aamar-shahzad-mcp-screenshot-server": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000"
      }
    }
  }
}

You run the MCP Screenshot Server to capture screenshots and annotate them with a rich set of tools. It supports smart annotations, AI-assisted placement, image loading, editing, and easy exporting. This guide walks you through using it with an MCP client, installing it, and configuring common options so you can start annotating images right away.

How to use

Connect an MCP client to the server and start a session to capture screenshots and load existing images for annotation. Use the unified annotation tool to add boxes, arrows, lines, circles, text, highlights, and borders. Take advantage of flexible positioning by choosing named positions (like top-left or center), percentages, or exact pixel coordinates. Adjust anchors and offsets to precisely align annotations, and enable automatic boundary adjustments so annotations stay within the image.

Perform multiple annotations in a single operation with batch capabilities, and label regions quickly when you need to describe several areas at once. For exact, coordinate-based work, switch to pixel-perfect mode to place elements with exact x/y coordinates. You can combine AI vision models to suggest coordinates and then confirm with precise annotations for pinpoint accuracy.

Capture new screenshots in full screen, a defined region, or a specific window, and you can also load existing image files to annotate them. Once your annotations are complete, export the final image in PNG, JPG, WebP, or other supported formats, or copy the result to the clipboard for quick sharing.

How to install

Prerequisites: you should have Python and a working network environment. You may also install via alternative tooling if you prefer the container or a packaging tool.

Install using Python’s package manager.

pip install mcp-screenshot-server

Install using the uv runtime (recommended for fast startup and development). Use uv add to install the package.

uv add mcp-screenshot-server

Alternatively, clone the project and install in editable mode to work with the source directly.

git clone https://github.com/aamar-shahzad/mcp-screenshot-server.git
cd mcp-screenshot-server
pip install -e .

Additional information

Configuration and runtime options let you run the server in different transports. The default stdio transport is suitable for Cursor AI and similar desktop workflows. You can also enable HTTP transport on port 8000 or switch to SSE transport as needed. Environment variables control the HTTP transport host and port, and you can pass these to the server as you start it.

Recommended startup commands from common usage are shown here for quick reference.

Troubleshooting and notes

If you run into permission issues on macOS, make sure screen recording is enabled for your terminal or IDE in System Preferences. On Linux, ensure clipboard tools are installed if clipboard operations fail. When running in Docker, remember that headless mode may affect screenshot capture, and you may need to run natively for full functionality.

Available tools

capture_screenshot

Capture a screenshot with the server and obtain an image identifier for further edits.

load_image

Load an existing image file into the current session for annotation.

precise_annotate

Apply pixel-perfect annotations at exact coordinates or dimensions.

annotate

Unified annotation tool with flexible positioning and auto-adjustment.

batch_annotate

Apply multiple annotations in a single call for efficiency.

label_regions

Label multiple regions with a single command for organization.

add_box

Draw rectangular boxes with customizable colors and fill.

add_line

Draw straight lines on the image.

add_arrow

Draw arrows with adjustable head size and direction.

add_text

Overlay text with options for font and background.

add_circle

Draw circles or ellipses on the image.

add_highlight

Create semi-transparent highlight regions.

add_numbered_callout

Add auto-numbered callouts for step-by-step guides.

add_border

Add borders around the image.

blur_region

Blur or pixelate regions to redact information.

crop_image

Crop the image to a specified region.

resize_image

Resize the image by scale or exact dimensions.

rotate_image

Rotate the image by 90/180/270 degrees.

flip_image

Flip the image horizontally or vertically.

adjust_brightness

Adjust brightness for appearance tuning.

adjust_contrast

Adjust contrast for emphasis.

add_watermark

Add a text watermark to the image.

undo

Undo the last annotation (up to 10 levels).

get_undo_count

Check how many undo steps remain.

reset_callout_counter

Reset auto-numbering for callouts.

list_images

List all images in the current session.

get_image

Retrieve a specific image by ID.

duplicate_image

Create a copy of an existing image.

delete_image

Remove an image from the session.

save_image

Save the image to disk in PNG, JPG, WebP, and other formats.

quick_save

Quickly save to common locations like Desktop.

copy_to_clipboard

Copy the image to the system clipboard.

get_image_base64

Get the image as a base64-encoded string.

open_in_preview

Open the image in the default viewer (macOS Preview or similar).

open_file_in_preview

Open any image file in the default viewer.