MCP Screenshot Server 📸

A powerful Model Context Protocol (MCP) server for capturing screenshots and annotating images with boxes, lines, arrows, circles, text, and highlights.

Features

🎯 Smart Annotation (NEW!)

• 🧠 Unified annotate Tool - One tool for all annotation types
• 📍 Flexible Positioning - Named positions ("top-left", "center"), percentages ("50%,30%"), or pixels
• ⚓ Anchor & Offset - Control which part of annotation aligns to position, with pixel-level fine-tuning
• 🔄 Auto-Adjust - Annotations automatically stay within image bounds
• ⚡ Batch Annotations - Apply multiple annotations in a single call
• 🏷️ Quick Labeling - Label multiple regions with one command
• 🎯 Pixel-Perfect Mode - precise_annotate for exact coordinate control

🤖 AI Vision Integration

• Works great with Gemini, Claude, and other vision models for intelligent annotation placement
• AI can analyze images and provide exact coordinates for annotations
• Combine vision analysis with precise_annotate for pinpoint accuracy

Capture & Load

• 📷 Screenshot Capture - Full screen, region, or window-specific captures
• 📂 Load Images - Load existing image files for annotation

Annotations

• 📦 Box Annotation - Draw rectangles with customizable colors and fill
• ➡️ Arrow Annotation - Draw directional arrows with adjustable head sizes
• 📏 Line Drawing - Simple line annotations
• ⭕ Circle/Ellipse - Draw circles and ellipses
• 📝 Text Overlay - Add text with custom fonts and backgrounds
• 🔦 Highlight Regions - Semi-transparent highlight overlays
• 🔢 Numbered Callouts - Auto-numbered callouts for step-by-step guides
• 🖼️ Border Tool - Add borders around images

Editing

• 🔲 Blur/Pixelate - Hide sensitive information (passwords, emails)
• ✂️ Crop - Crop images to specific regions
• 📐 Resize - Resize with scale or exact dimensions
• 🔄 Rotate/Flip - Rotate 90/180/270 degrees, flip horizontal/vertical
• 🌓 Brightness/Contrast - Adjust image appearance
• 💧 Watermark - Add text watermarks
• ↩️ Undo - Undo annotations (up to 10 levels)

Export

• 💾 Save Images - Export to PNG, JPG, WebP, and more
• ⚡ Quick Save - One-click save to Desktop/Downloads
• 📋 Clipboard Support - Copy images directly to system clipboard
• 👁️ Preview Integration - Open in macOS Preview.app for native editing
• 🐳 Docker Ready - Run as a containerized service

Examples

Screenshots captured from the browser and annotated using the MCP Screenshot Server tools:

Basic Annotations

Box, arrow, text, highlight, and circle annotations:

Numbered Callouts

Step-by-step guides with numbered markers:

Highlights & Regions

Highlight important sections and mark areas for blur:

Pixel-Perfect Annotations

Using precise_annotate with exact coordinates:

PII Redaction

Blur or redact sensitive information:

Quick Start

Installation

# Using pip
pip install mcp-screenshot-server

# Using uv (recommended)
uv add mcp-screenshot-server

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

Running the Server

# stdio transport (default - for Cursor AI, Claude Desktop, etc.)
mcp-screenshot-server

# HTTP transport (for web clients)
mcp-screenshot-server --transport streamable-http --port 8000

# SSE transport
mcp-screenshot-server --transport sse --port 8000

Integration with Cursor AI

Method 1: Local Installation (Recommended)

1. Install the package:

   pip install mcp-screenshot-server
   # or
   uv tool install mcp-screenshot-server
   

2. Add to Cursor settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):

   {
     "mcpServers": {
       "screenshot": {
         "command": "mcp-screenshot-server",
         "args": []
       }
     }
   }
   

3. Restart Cursor to load the MCP server.

Method 2: Using uvx (No Installation)

{
  "mcpServers": {
    "screenshot": {
      "command": "uvx",
      "args": ["mcp-screenshot-server"]
    }
  }
}

Method 3: Using Docker

1. Build the Docker image:

   docker build -t mcp-screenshot-server .
   

2. Add to Cursor settings:

   {
     "mcpServers": {
       "screenshot": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "mcp-screenshot-server"]
       }
     }
   }
   

Method 4: HTTP Transport

1. Start the server:

   mcp-screenshot-server --transport streamable-http --port 8000
   

2. Add to Cursor settings:

   {
     "mcpServers": {
       "screenshot": {
         "url": "http://localhost:8000/mcp"
       }
     }
   }
   

Available Tools

🎯 Smart Annotation Tools (Recommended!)

These tools use flexible positioning and auto-adjustment for easier annotation:

Position Formats:

• Named: "top-left", "center", "bottom-right", "top-right-quarter", etc.
• Percentage: "50%, 30%" (from top-left)
• Pixels: "100px, 200px" (absolute coordinates)

Anchor Options (controls which part of annotation aligns to position):

• "top-left", "top-center", "top-right"
• "center-left", "center", "center-right"
• "bottom-left", "bottom-center", "bottom-right"

Examples:

# Smart annotation with anchor and offset
annotate(img, "box", "830px, 195px", width=140, height=55,
         anchor="top-left", offset_x=0, offset_y=0)

# Pixel-perfect annotation (no transformations)
precise_annotate(img, "box", x=830, y=195, width=140, height=55, color="blue")
precise_annotate(img, "text", x=830, y=168, text="Code Button", font_size=24)
precise_annotate(img, "arrow", x=100, y=200, x2=300, y2=200, color="red")

# Multiple annotations in one call
batch_annotate(img, '[{"type":"box","position":"top-left"},{"type":"text","position":"center","text":"Hello"}]')

# Label multiple regions at once
label_regions(img, '{"Header":"top-center","Sidebar":"center-left","Main":"center"}')

🤖 Using with AI Vision Models

For the most accurate annotations, combine with vision-capable AI models:

1. Take screenshot with browser/capture tool
2. AI (Gemini/Claude) analyzes image and identifies element coordinates
3. Use precise_annotate with exact coordinates from AI
4. Result: pixel-perfect annotations every time

Screenshot Capture

Basic Annotation Tools (for pixel-precise control)

Editing Tools

Image Management

Export Tools

macOS Preview Integration

On macOS, you can use the open_in_preview tool to open images in the native Preview.app, which provides additional markup tools.

Preview's Native Tools:

• ✏️ Sketch - Freehand drawing
• ⬜ Shapes - Rectangles, circles, arrows, speech bubbles
• 📝 Text - Add text boxes with custom fonts
• ✍️ Signature - Add your saved signature
• 🎨 Colors - Full color picker
• 📏 Border - Adjust line thickness

This allows you to combine MCP annotations with Preview's native tools for more complex edits.

Usage Examples

Basic Screenshot and Annotation

# In Cursor AI, you can ask:
# "Take a screenshot and add a red box around the error message"

# The AI will use these tools:
# 1. capture_screenshot() -> returns image_id
# 2. add_box(image_id, x=100, y=200, width=300, height=50, color="red")
# 3. save_image(image_id, path="~/Desktop/annotated.png")

Creating a Bug Report Screenshot

User: Take a screenshot of my screen and highlight the button at coordinates
      (500, 300) with a red circle, add an arrow pointing to it, and save it.

AI uses:
1. capture_screenshot(mode="fullscreen")
2. add_circle(image_id, x=500, y=300, radius=40, color="red", line_width=3)
3. add_arrow(image_id, x1=400, y1=200, x2=480, y2=280, color="red")
4. add_text(image_id, x=350, y=180, text="Click here!", color="red")
5. save_image(image_id, path="~/Desktop/bug-report.png")

Annotating an Existing Image

User: Load the image at ~/Downloads/mockup.png and add numbered callouts

AI uses:
1. load_image(path="~/Downloads/mockup.png")
2. add_circle(image_id, x=100, y=100, radius=20, color="blue", fill="blue")
3. add_text(image_id, x=92, y=88, text="1", color="white")
4. add_circle(image_id, x=300, y=200, radius=20, color="blue", fill="blue")
5. add_text(image_id, x=292, y=188, text="2", color="white")
6. save_image(image_id, path="~/Downloads/mockup-annotated.png")

Docker Usage

Build and Run

# Build the image
docker build -t mcp-screenshot-server .

# Run with stdio transport
docker run -i --rm mcp-screenshot-server

# Run with HTTP transport
docker run -p 8000:8000 mcp-screenshot-server \
    --transport streamable-http --port 8000

# Run with volume for saving screenshots
docker run -p 8000:8000 -v $(pwd)/screenshots:/app/screenshots \
    mcp-screenshot-server --transport streamable-http

Docker Compose

# Start HTTP server
docker-compose up -d mcp-screenshot-server

# Start stdio server
docker-compose --profile stdio up -d mcp-screenshot-server-stdio

Configuration

Environment Variables

Command Line Arguments

mcp-screenshot-server [OPTIONS]

Options:
  --transport {stdio,streamable-http,sse}
                        Transport to use (default: stdio)
  --host HOST           Host for HTTP transports (default: 0.0.0.0)
  --port PORT           Port for HTTP transports (default: 8000)

Platform Support

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/aamar-shahzad/mcp-screenshot-server.git
cd mcp-screenshot-server

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/

Project Structure

mcp-screenshot-server/
├── src/
│   └── mcp_screenshot_server/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── README.md
└── LICENSE

Troubleshooting

macOS: "screencapture" requires screen recording permission

Go to System Preferences > Privacy & Security > Screen Recording and enable the terminal or IDE you're using.

Linux: Clipboard not working

Install clipboard tools:

# For X11
sudo apt install xclip

# For Wayland
sudo apt install wl-clipboard

Docker: Screenshots are blank

The Docker container runs in headless mode. For actual screen capture, you need to run the server natively on the host system.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with MCP Python SDK
• Image processing powered by Pillow