screenshooter-mcp

README

ScreenshooterMCP

MCP server enabling AI agents to take screenshots on Linux (X11 and Wayland).

Features

• list_monitors - List available displays with names, positions, and dimensions
• list_windows - List open windows with titles and IDs
• capture_screen - Capture full screen or specific monitor (returns PNG)
• capture_window - Capture window by title (partial match supported)
• capture_region - Capture rectangular region from screen (returns PNG)

Installation

From Packages

Pre-compiled packages for Debian/Ubuntu and Fedora (x86_64 and ARM64):

Distribution	Package Type	Install
Debian/Ubuntu	.deb	dpkg -i screenshooter-mcp-*.deb
Fedora	.rpm	dnf install screenshooter-mcp-*.rpm

Static Binaries

Pre-compiled static binaries are available for all other Linux distributions.

From Source

go build -o screenshooter-mcp ./cmd/screenshooter-mcp-server

Usage

Stdio Mode (Default)

Run without arguments for stdio mode (works with Claude Desktop, Cursor, etc.):

./screenshooter-mcp

HTTP Server Mode

Run as HTTP server:

./screenshooter-mcp --listen 127.0.0.1:11777

Or configure in config file:

{
  "listen": "127.0.0.1:11777"
}

Configuration

Config file locations (in priority order):

1. $XDG_CONFIG_HOME/screenshooter-mcp/config.json (default: ~/.config/screenshooter-mcp/config.json)
2. /etc/screenshooter-mcp/config.json (system default)

Options:

Field	Type	Default	Description
log_level	string	"info"	Log level: debug, info, warn, error
color	string	"auto"	Color output: always, never, auto
listen	string	""	HTTP listen address or empty for stdio

CLI Options

-v, --version           Show version
-h, --help            Show help
--config              Path to config file
-l, --log-level       Log level: debug|info|warn|error
--color               Color output: always|never|auto
--listen             Listen on TCP address (e.g. 127.0.0.1:11777) or 'stdio'
--stdio              Force stdio mode (overrides --listen)

Configuration

Configuration is loaded from (in order of priority):

1. --config CLI flag
2. SCREENSHOOTER_CONFIG environment variable
3. User config: $XDG_CONFIG_HOME/screenshooter-mcp/config.json (default: ~/.config/screenshooter-mcp/config.json)
4. System config: /etc/screenshooter-mcp/config.json

Default config:

{
  "log_level": "info",
  "color": "auto",
  "listen": ""
}

MCP Tools

list_monitors

List all available monitors with their names and aliases.

{
  "Name": "DP-1.1",
  "Aliases": ["right-1920x1080", "DP-1.1", "1"],
  "X": 1920, "Y": 0,
  "Width": 1920, "Height": 1080
}

list_windows

List all open windows with their titles and X11 window IDs.

capture_screen

Capture the full screen or a specific monitor.

Arguments:

• monitor (optional): Monitor name or alias

capture_window

Capture a window by its title (partial match supported).

Arguments:

• title: Window title to capture

capture_region

Capture a region from the virtual screen.

Arguments:

• x: X coordinate
• y: Y coordinate
• width: Width
• height: Height

Requirements

X11

• X11 server with RANDR extension

Wayland

• wlroots-based compositor (recommended)
• or xdg-desktop-portal backend

License

MIT