MCP Screenshot Server - Clean Version

A reliable Model Context Protocol server for taking screenshots with timestamp overlays.

Project Structure

mcp-screenshot-server/
├── screenshot_server.py        # Main server file
├── config.py                   # Configuration settings
├── screenshot_utils.py         # Screenshot utilities
├── requirements.txt           # Python dependencies
└── README.md                  # This file

Related MCP server: Screenshot MCP (macOS)

Installation

1. Create Project Directory

mkdir mcp-screenshot-server
cd mcp-screenshot-server

2. Create the Files

Create each file with the contents from the artifacts above:

• screenshot_server.py - Main server

• config.py - Configuration

• screenshot_utils.py - Utilities

• requirements.txt - Dependencies

3. Install Dependencies

# Using your specific Python environment
/Users/antond/.pyenv/versions/3.12.4/envs/python_3_12/bin/pip install -r requirements.txt

4. Test the Server

cd mcp-screenshot-server
/Users/antond/.pyenv/versions/3.12.4/envs/python_3_12/bin/python screenshot_server.py

You should see: "Starting MCP Screenshot Server..." and "Screenshots will be saved to: /Users/antond/Downloads/MCP_Screenshots"

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/antond/Desktop",
        "/Users/antond/Downloads"
      ]
    },
    "screenshot": {
      "command": "/Users/antond/.pyenv/versions/3.12.4/envs/python_3_12/bin/python",
      "args": ["/full/path/to/mcp-screenshot-server/screenshot_server.py"]
    }
  }
}

Customizing Settings

Edit config.py to change:

• Screenshots directory path

• Supported image formats

• Default timestamp format

• Font paths for different systems

Features

✅ Core Screenshots

• Full screen capture

• Region-based screenshots

• Multiple formats (PNG, JPG, BMP, TIFF)

• Custom filenames with automatic timestamping

✅ Timestamp Overlays

• Customizable position (5 locations)

• Font size control (8-72px)

• Color customization

• Semi-transparent backgrounds

• Custom date/time formats

✅ File Management

• List all screenshots with metadata

• File size and dimensions info

• Creation/modification timestamps

• Automatic directory organization

✅ Cross-Platform

• macOS, Windows, Linux support

• Automatic font detection

• Screen info detection

Usage Examples

Once configured in Claude Desktop:

Basic Screenshots

• "Take a screenshot"

• "Take a screenshot called 'my_desktop'"

• "Take a screenshot in JPG format"

Region Screenshots

• "Take a screenshot of region x=100, y=100, width=800, height=600"

Timestamped Screenshots

• "Take a screenshot with timestamp"

• "Take a screenshot with timestamp in top-right corner"

• "Take a screenshot with large timestamp"

File Management

• "List all my screenshots"

• "Show screen information"

Troubleshooting

Permission Issues (macOS)

Grant screen recording permissions:

1. System Preferences → Security & Privacy → Screen Recording

2. Add Claude Desktop to allowed apps

3. Restart Claude Desktop

Import Errors

# Ensure all dependencies are installed
/Users/antond/.pyenv/versions/3.12.4/envs/python_3_12/bin/pip install --upgrade -r requirements.txt

Path Issues

• Use absolute paths in Claude Desktop configuration

• Verify Python executable path with: which python

• Check file permissions in project directory

Architecture Benefits

🏗️ Clean Separation

• screenshot_server.py: MCP server handling

• config.py: All settings in one place

• screenshot_utils.py: Core screenshot logic

🔧 Easy Maintenance

• Modular design for easy updates

• Clear error handling and logging

• Configurable without code changes

🚀 Reliable Performance

• No external browser dependencies

• Uses proven pyautogui library

• Robust error handling

📦 Simple Deployment

• Minimal dependencies

• Self-contained project

• Easy to backup and share

This clean, modular approach gives you a solid foundation for reliable screenshot functionality that's easy to maintain and extend!