Linux/X11 port of Peekaboo — brings screen capture, UI element detection, and GUI automation to Ubuntu.
- Ubuntu 20.04+ (ARM or x86_64)
- X11 display server
- Python 3.8+
- Node.js 18+ (for MCP server wrapper, optional)
sudo apt-get install -y \
xdotool wmctrl xclip imagemagick scrot \
at-spi2-core libatspi2.0-dev gir1.2-atspi-2.0 \
python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
libx11-dev libxtst-devcd peekaboo-linux
pip3 install -e .peekaboo --version
peekaboo see# Capture full screen
peekaboo image --path ~/screenshot.png
# See UI elements (accessibility tree + screenshot)
peekaboo see --json-output
# Click a button by element ID
peekaboo click --on B1
# Click by text search
peekaboo click --query "Save"
# Click by coordinates
peekaboo click --coords "100,200"
# Type text
peekaboo type --text "Hello world" --on T1
# Keyboard shortcut (Ctrl+C)
peekaboo hotkey --keys "ctrl,c"
# List running apps
peekaboo app --action list
# Window management
peekaboo window --action maximize --app firefox
# Run as MCP server
peekaboo mcp serveUse with Claude Code, Cursor, or any MCP-compatible client:
{
"mcpServers": {
"peekaboo": {
"command": "python3",
"args": ["-m", "peekaboo", "mcp", "serve"]
}
}
}Or with the Node.js wrapper (crash-restart):
{
"mcpServers": {
"peekaboo": {
"command": "node",
"args": ["/path/to/peekaboo-linux/peekaboo-mcp.js"]
}
}
}| Tool | Description |
|---|---|
see |
Capture screenshot + generate element map (B1, T1, L1...) |
image |
Capture screenshot |
click |
Click by element ID, text query, or coordinates |
type |
Type text into elements |
scroll |
Scroll in any direction |
hotkey |
Press keyboard shortcuts |
move |
Move mouse cursor |
drag |
Drag and drop |
set_value |
Set element value directly |
perform_action |
Invoke accessibility action |
app |
Launch/quit/focus/hide applications |
window |
Close/minimize/maximize/move/resize windows |
menu |
List/click menu items |
clipboard |
Read/write clipboard |
paste |
Atomic paste (set clipboard + Ctrl+V + restore) |
space |
Virtual desktop management |
list |
List apps/windows/server status |
sleep |
Pause execution |
Cmdshortcuts are mapped toCtrl(e.g. Cmd+C → Ctrl+C)- No permissions required (X11 is open by default)
docktool not available (no universal Linux equivalent)- AT-SPI2 accessibility coverage varies by toolkit (GTK apps work best)
AT-SPI2 not finding elements:
# Ensure AT-SPI2 bus is running
export GTK_MODULES=gail:atk-bridge
export QT_ACCESSIBILITY=1xdotool not working:
# Check DISPLAY is set
echo $DISPLAY
# Should output something like ":0" or ":1"MIT