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
annotateTool - 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_annotatefor 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_annotatefor 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)
-
Install the package:
pip install mcp-screenshot-server # or uv tool install mcp-screenshot-server -
Add to Cursor settings (
~/.cursor/mcp.jsonor workspace.cursor/mcp.json):{ "mcpServers": { "screenshot": { "command": "mcp-screenshot-server", "args": [] } } } -
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
-
Build the Docker image:
docker build -t mcp-screenshot-server . -
Add to Cursor settings:
{ "mcpServers": { "screenshot": { "command": "docker", "args": ["run", "-i", "--rm", "mcp-screenshot-server"] } } }
Method 4: HTTP Transport
-
Start the server:
mcp-screenshot-server --transport streamable-http --port 8000 -
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:
| Tool | Description |
|---|---|
annotate | Unified annotation with smart positioning |
precise_annotate | Pixel-perfect annotations at exact coords |
batch_annotate | Apply multiple annotations in ONE call |
label_regions | Quickly label multiple areas with one command |
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
| Tool | Description |
|---|---|
capture_screenshot | Capture full screen, region, or window screenshots |
load_image | Load an existing image file for annotation |
Basic Annotation Tools (for pixel-precise control)
| Tool | Description |
|---|---|
precise_annotate | NEW! Pixel-perfect multi-type tool |
add_box | Draw rectangles/boxes on images |
add_line | Draw lines on images |
add_arrow | Draw arrows on images |
add_text | Add text annotations |
add_circle | Draw circles/ellipses |
add_highlight | Add semi-transparent highlight regions |
add_numbered_callout | Add auto-numbered callouts (1, 2, 3...) |
add_border | Add border around entire image |
Editing Tools
| Tool | Description |
|---|---|
blur_region | Blur/pixelate sensitive areas |
crop_image | Crop image to specific region |
resize_image | Resize with scale or dimensions |
rotate_image | Rotate 90, 180, or 270 degrees |
flip_image | Flip horizontal or vertical |
adjust_brightness | Adjust image brightness |
adjust_contrast | Adjust image contrast |
add_watermark | Add text watermark |
undo | Undo last annotation (up to 10 levels) |
get_undo_count | Check available undo operations |
reset_callout_counter | Reset auto-numbering to 0 |
Image Management
| Tool | Description |
|---|---|
list_images | List all images in the current session |
get_image | Get a specific image by ID |
duplicate_image | Create a copy of an existing image |
delete_image | Remove an image from the session |
Export Tools
| Tool | Description |
|---|---|
save_image | Save image to disk (PNG, JPG, WebP, etc.) |
quick_save | Quick save to Desktop/Downloads/Documents |
copy_to_clipboard | Copy image to system clipboard |
get_image_base64 | Get image as base64-encoded string |
open_in_preview | Open image in macOS Preview or default viewer |
open_file_in_preview | Open any image file in Preview/default viewer |
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
| Variable | Description | Default |
|---|---|---|
MCP_HOST | Host for HTTP transport | 0.0.0.0 |
MCP_PORT | Port for HTTP transport | 8000 |
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
| Platform | Screenshot | Clipboard | Notes |
|---|---|---|---|
| macOS | ✅ Native screencapture | ✅ AppleScript | Full support |
| Windows | ✅ PIL ImageGrab | ✅ PowerShell | Full support |
| Linux | ✅ PIL/scrot | ✅ xclip/wl-copy | Requires X11/Wayland |
| Docker | ✅ With Xvfb | ⚠️ Limited | Headless mode |
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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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