antondemidov/screenshot-mcp-server

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

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!