Auto-Snap

Auto-Snap MCP is a local automation server that lets your MCP client capture windows, process screenshots, and generate PDFs using natural language commands. It helps you turn visual content from your screen into organized documents with zero or minimal setup.

How to use

You enable Auto-Snap MCP as a connected MCP server and then interact with it through your MCP client. Start by listing your open windows to confirm connectivity, then issue commands to capture windows or screens and convert them into PDFs. You can perform multi-page captures, apply OCR to extract text, and organize outputs with smart naming and optional compression.

Typical usage patterns include:

• List all my open windows to see what you can capture
• Capture this PDF to convert a current view or document
• Take 5 screenshots and make them into a PDF for multi-page documents
• Extract text from these images to perform OCR and searchability
• Archive a presentation by capturing each slide into a single PDF

Pro tips for reliable results include: be specific when naming the window you want to capture, use multi-step commands to combine actions (for example, screenshot this presentation and extract all the text), and batch process images to quickly produce a set of PDFs.

How to install

Prerequisites depend on your environment. You can run Auto-Snap MCP via Docker for the easiest setup, or run locally with WSL2 on Windows or native Linux.

1. Get Auto-Snap MCP set up on your machine by cloning the project and entering the directory.

git clone https://github.com/your-repo/auto-snap-mcp
cd auto-snap-mcp

2. Install dependencies (Linux only) if you are not using Docker. You may also need to sync dependencies via uv.

sudo apt install -y wmctrl xdotool tesseract-ocr
uv sync

3. Configure Claude Desktop with one of the MCP server options. Use the following JSON blocks in your Claude Desktop configuration under the MCP servers section.

{
  "mcpServers": {
    "auto-snap-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DISPLAY=:0", 
        "-v", "/tmp/.X11-unix:/tmp/.X11-unix:rw",
        "-v", "${HOME}/auto-snap-captures:/app/captures:rw",
        "mcp/auto-snap-mcp:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "auto-snap-mcp": {
      "command": "wsl.exe",
      "args": [
        "bash", "-c",
        "cd /home/YOUR_WSL_USERNAME/auto-snap-mcp && DISPLAY=:0 /home/YOUR_WSL_USERNAME/.local/bin/uv run python server.py"
      ]
    }
  }
}

{
  "mcpServers": {
    "auto-snap-mcp": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/home/YOUR_USERNAME/auto-snap-mcp",
      "env": {"DISPLAY": ":0"}
    }
  }
}

Additional setup notes

Restart Claude Desktop after you complete the configuration, then test connectivity by asking to list your open windows and perform a simple capture to verify that Auto-Snap MCP is reachable.

Customize your captures

You can steer where files are saved and how they are organized by setting environment variables in your shell before starting Claude Desktop.

export AUTO_SNAP_OUTPUT_DIR="$HOME/Documents/Screenshots"

export AUTO_SNAP_USE_DATE_SUBDIRS=true
export AUTO_SNAP_INCLUDE_TIMESTAMP=true

export AUTO_SNAP_FILE_NAME_TEMPLATE="doc_{page:04d}"

Privacy

All processing runs locally on your machine with no cloud services involved. Your captures are kept private and only used for the actions you request, with automatic cleanup of temporary files.

Troubleshooting

If things aren’t working, check dependencies and the display configuration. Ensure the correct config path is used and restart Claude Desktop after any changes.

uv run python -c "from capture import check_dependencies; print(check_dependencies())"
export DISPLAY=:0
uv run python server.py

Notes and reminders

If you need to change where files are saved later, adjust the environment variables described in the customization section. You can also enable multi-language OCR by installing additional tesseract language packs.

Available tools

Document Capture

Capture windows or the full screen, including multi-page documents, and prepare inputs for processing.

Image Processing

Perform OCR on screenshots, enhance images, and handle multiple images in a batch.

PDF Creation

Convert captures into PDFs, with options for naming and compression.

Commands to Control

Interact using natural language commands to drive captures, OCR, and PDF output.