triepod-ai/snap-happy-mcp

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.

About This Fork

This is an enhanced fork of the original snap-happy MCP server with full Windows/WSL2 support. The upstream implementation was macOS-focused, and this fork adds comprehensive Windows and WSL2 functionality.

Key Enhancements in This Fork

• ✅ Full Windows/WSL2 Support: Native PowerShell integration with .NET Framework for screenshot capture
• ✅ Window-Specific Screenshots on Windows: Capture individual windows using Win32 PrintWindow API
• ✅ Automatic WSL Path Conversion: Seamlessly converts /mnt/c/ paths to C:\ format
• ✅ ListWindows for Windows: Enumerate all visible Windows applications with IDs, titles, and positions
• ✅ WSL2 Auto-Detection: Automatically detects WSL2 environments via WSL_DISTRO_NAME environment variable
• ✅ PowerShell Script Management: Robust temporary script handling with automatic cleanup

Repository: triepod-ai/snap-happy-mcp

Features

• Cross-platform screenshot capture: Works on macOS, Linux, Windows, and WSL2 environments
• 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)
    • Windows/WSL2: Full screen or specific window capture using Win32 PrintWindow API
    • Linux: Full screen capture only
  • ListWindows(): Lists all visible windows with IDs, titles, and application names (macOS and Windows)
• Window-specific screenshots: On macOS and Windows, capture individual windows without interference from overlapping content
• Screenshot optimization: Resize, format conversion (PNG/JPEG), and quality control options

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/WSL2: PowerShell with .NET Framework (automatic WSL path conversion)

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.

Windows/WSL2 Configuration

For WSL2 environments, the server automatically converts WSL paths to Windows paths:

# WSL2 path (automatically converted to Windows format)
export SNAP_HAPPY_SCREENSHOT_PATH="/mnt/c/Users/username/Screenshots"

# Or use Windows path directly
export SNAP_HAPPY_SCREENSHOT_PATH="C:\Users\username\Screenshots"

The server detects WSL2 environments using the WSL_DISTRO_NAME environment variable and handles path conversion automatically.

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

Windows/WSL2 Setup

The server automatically handles Windows/WSL2 environments:

• Platform Detection: Detects WSL2 via WSL_DISTRO_NAME environment variable
• Path Conversion: Automatically converts /mnt/c/path to C:\path format
• PowerShell Integration: Uses full PowerShell path in WSL2 (/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe)
• Debug Logging: Enable debug logs by checking console output for troubleshooting

Windows-Specific Features

• ListWindows: Successfully lists all Windows applications with IDs, titles, and positions
• TakeScreenshot: Captures full desktop screenshots with .NET Framework integration
• GetLastScreenshot: Retrieves most recent screenshot as base64 data

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 and Windows": Window capture with windowId parameter works on macOS and Windows (Linux currently supports full screen only)
• WSL2 Path Issues: The server automatically converts WSL paths - no manual conversion needed
• PowerShell Execution: On Windows, ensure PowerShell execution policy allows script execution
• Native utility build errors: Only relevant for development - end users get pre-built binaries. For development, ensure Swift compiler is available (xcode-select --install)

Debug Logging

For troubleshooting Windows/WSL2 issues, check console output for debug messages:

• [DEBUG]: Information about script paths and PowerShell execution
• [ERROR]: Detailed error messages with command paths and file existence checks

License

MIT License - see LICENSE file for details.