Snap Happy

https://github.com/user-attachments/assets/f2a96139-70ae-44db-b924-ac7b043a9f00

A Model Context Protocol (MCP) server that provides screenshot functionality for AI assistants. Take screenshots and retrieve recent captures programmatically across macOS, Linux, and Windows.

Features

• Cross-platform screenshot capture: Works on macOS, Linux, and Windows (only tested on macOS. Works on my machine)
• Three main tools:
  • GetLastScreenshot(): Returns the most recent screenshot as base64 PNG
  • TakeScreenshot(): Takes a new screenshot and returns it as base64 PNG
    • macOS: Full screen or specific window capture (captures actual window content, ignoring overlapping windows)
    • Linux/Windows: Full screen capture only
  • ListWindows(): Lists all visible windows with IDs, titles, and application names (macOS only)
• Window-specific screenshots: On macOS, capture individual windows without interference from overlapping content

Installation

npm install -g @mariozechner/snap-happy

Prerequisites

• macOS: Built-in screencapture command and Swift compiler (Screen Recording permission required for window capture)
• Linux: gnome-screenshot or scrot package
• Windows: PowerShell with .NET Framework

Build Requirements

The package includes pre-built universal binaries for macOS (Intel + Apple Silicon). End users don't need any additional tools.

For development/publishing:

• macOS: Swift compiler (Xcode or Swift toolchain) to build universal binaries
• Linux/Windows: No additional build requirements

Configuration

Optionally set an environment variable for your screenshot directory:

export SNAP_HAPPY_SCREENSHOT_PATH="/path/to/screenshots"

The directory will be created automatically if it doesn't exist.

Usage

With Claude Code

# Add the MCP server
claude mcp add snap-happy npx @mariozechner/snap-happy

# Use in Claude
echo "Take a screenshot" | claude -p
echo "Show me the last screenshot" | claude -p

As MCP Server

Add to your MCP client configuration:

{
	"mcpServers": {
		"snap-happy": {
			"command": "npx",
			"args": ["@mariozechner/snap-happy"],
			"env": {
				"SNAP_HAPPY_SCREENSHOT_PATH": "/Users/username/Screenshots"
			}
		}
	}
}

Development

# Start building in watch mode
npm run dev

# Build everything (TypeScript + universal binaries for distribution)
npm run build

# Build for development (current architecture only, faster)
npm run build:dev

# Build only native utilities (universal binaries)
npm run build:native

# Build only native utilities (development, current architecture)
npm run build:native:dev

# Add to Claude for testing (after building)
claude mcp add snap-happy node /path/to/git/clone/of/snap-happy/dist/index.js

# Test using Claude Code
echo "Take a screenshot" | claude -p

# Test with JSON-RPC directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "ListWindows", "arguments": {}}}' | node dist/index.js
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "TakeScreenshot", "arguments": {"windowId": 2}}}' | node dist/index.js

# Run all tests
npm test

Troubleshooting

macOS Permissions

On first use, macOS will prompt for permissions:

• Screen Recording: Required for taking screenshots and window capture
• Window listing uses Core Graphics APIs and doesn't require additional permissions. Might trigger some macOS security bullshit tho. Works on my machine.

Grant permissions in System Preferences → Security & Privacy → Privacy → Screen Recording.

Linux Dependencies

# Ubuntu/Debian
sudo apt install gnome-screenshot

# Fedora/RHEL
sudo dnf install gnome-screenshot

Common Issues

• "Environment variable not set": Set SNAP_HAPPY_SCREENSHOT_PATH
• "Screenshot path is not writable": Check directory permissions
• "No screenshots found": Verify directory contains PNG files
• "Window-specific screenshots are only supported on macOS": Window capture with windowId parameter only works on macOS
• Native utility build errors: Only relevant for development - end users get pre-built binaries. For development, ensure Swift compiler is available (xcode-select --install)

License

MIT License - see LICENSE file for details.