# MCP Screenshot Server 📸
A powerful [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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
```bash
# 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
```bash
# 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**:
```bash
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`):
```json
{
"mcpServers": {
"screenshot": {
"command": "mcp-screenshot-server",
"args": []
}
}
}
```
3. **Restart Cursor** to load the MCP server.
### Method 2: Using uvx (No Installation)
```json
{
"mcpServers": {
"screenshot": {
"command": "uvx",
"args": ["mcp-screenshot-server"]
}
}
}
```
### Method 3: Using Docker
1. **Build the Docker image**:
```bash
docker build -t mcp-screenshot-server .
```
2. **Add to Cursor settings**:
```json
{
"mcpServers": {
"screenshot": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-screenshot-server"]
}
}
}
```
### Method 4: HTTP Transport
1. **Start the server**:
```bash
mcp-screenshot-server --transport streamable-http --port 8000
```
2. **Add to Cursor settings**:
```json
{
"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:**
```python
# 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
```python
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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](LICENSE) file for details.
## Acknowledgments
- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Image processing powered by [Pillow](https://pillow.readthedocs.io/)
