Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mango-mcp launch Firefox on tag 2, then screenshot the window"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives an agent its own computer to use: a private, headless mango desktop running next to yours. The agent launches apps, takes screenshots, and drives the mouse and keyboard there. None of it reaches your session: your cursor stays put, your focus is never taken, nothing appears on your screen, and your typing never lands in the agent's windows.
You do not need to use mango yourself. The agent's desktop is a separate headless compositor, so this works from any desktop (GNOME, KDE, Sway, Hyprland, ...), or none.
The flake bundles everything (mango, grim, wtype, dbus-daemon):
claude mcp add --scope user mango-desktop -- nix run github:Anti-2k/mango-mcpOr build a local copy: git clone https://github.com/Anti-2k/mango-mcp && cd mango-mcp && nix build, then point your client at result/bin/mango-mcp.
Install mango and the helper tools:
Distro | Command | mango |
Arch |
| official repos |
Fedora |
| needs the Terra repo |
Gentoo |
| GURU overlay |
Guix |
| |
Debian, Ubuntu |
| |
openSUSE |
| |
Void |
| build from source |
Package names drift; repology has the current ones. mango 0.12 and newer (including 0.18+) are supported.
Install the server (Python 3.10+) with uv or pipx:
uv tool install git+https://github.com/Anti-2k/mango-mcp
# or: pipx install git+https://github.com/Anti-2k/mango-mcpThe prebuilt pywayland wheels need glibc 2.34+ on x86_64 (Debian 12,
Ubuntu 22.04, Fedora 35 and later). Elsewhere pip builds it from source,
which needs the Wayland development headers and libffi.
Check that everything is found, then register it:
mango-mcp check
claude mcp add --scope user mango-desktop -- mango-mcpAny other MCP client: run mango-mcp as a stdio server. The desktop starts on
the first tool call and is torn down, along with every app the agent started,
when the server exits.
Variable | Default | Meaning |
|
| Desktop name. A second server with the same name gets |
|
| Size of the headless screen. |
|
| Tags the agent may use, e.g. |
| unset |
|
| unset | Comma-separated variables to pass through anyway, e.g. |
| bundled | Use a different mango binary. 0.12 (dwl-ipc) and 0.18 (socket IPC) are both supported. |
Related MCP server: deskwright
Tool | |
| Screen size, tags (which are visible, window counts), focused window |
| Whole screen or a region; |
| A region magnified (up to 4x by default) to read small text |
| Run a shell command on the desktop, optionally on a given tag; reports the new window |
| Run a short command in the desktop's environment and return its output (killed after |
| Window management ( |
| Tags, limited to |
| Pointer, in screen pixels |
| Keyboard: any Unicode text regardless of layout; combos like |
|
eval "$(result/bin/mango-mcp env agent)" # point this shell at the agent desktop
grim /tmp/agent.png # one-off screenshot
nix run nixpkgs#wayvnc -- -d 127.0.0.1 5900 # live view in any VNC viewerKeep the -d (--disable-input) on wayvnc. Without it, input from the viewer
goes to the agent's seat and you would be interfering with the agent.
The agent gets a separate compositor rather than a corner of yours. Mango, like dwl, has one seat (one cursor, one keyboard focus), so inside a single session any synthetic click or keystroke would have to move your cursor and take your focus.
Way the two sides could interfere | What prevents it |
Your keyboard and mouse reaching the agent | The agent's mango runs on the headless backend with no libinput devices. It has no physical input at all. |
Agent input reaching your windows | Input goes in through the virtual-pointer and virtual-keyboard protocols, over the agent's own Wayland socket. Nothing uses |
Agent apps opening on your screen | Every process gets a freshly built environment: its own |
Single-instance apps handing off to your copy | A private D-Bus session bus, plus by default a separate |
Notifications, portals and other D-Bus services showing up on your desktop | The private bus. Services activated on it inherit the agent's display. |
mango rewriting your session's environment | mango runs |
Compositor keybindings | The agent's config has no binds and no autostart ( |
Two agents fighting over one desktop | Each server takes an exclusive lock on its desktop name. |
tests/test_live.py checks this end to end: it starts a desktop, drives a
terminal in it, then asserts that your systemctl --user show-environment and
the contents of your runtime directory are unchanged.
This keeps the agent and you from getting in each other's way. It is not a
security sandbox. Agent processes run as your user, with your files and
network. A process that deliberately sets WAYLAND_DISPLAY=wayland-0 XDG_RUNTIME_DIR=/run/user/$UID can still reach your session. Some leaks also
bypass the environment entirely:
gpg finds its agent at a fixed path, so signing inside the agent desktop can
pop a pinentry dialog on your screen.
/tmp/.X11-unix is shared, so an agent app explicitly told DISPLAY=:0
would reach your Xwayland.
Covering those needs mount namespaces (e.g. bubblewrap). That is not done here.
With MANGO_MCP_SHARE_HOME=1, an app that is already running on your desktop
(Chromium, VS Code, Discord, ...) may receive the agent's launch and open the
window on your screen. To use those apps with a shared home, give them a
separate profile (--user-data-dir, firefox --profile ... --new-instance).
MIT, see LICENSE. The Wayland protocol XML files in
mango_mcp/protocols/ are third-party and keep their own terms.
nix develop
python -m pytest # unit tests
MANGO_MCP_LIVE=1 python -m pytest # plus the live end-to-end test (needs kitty)
MANGO_MCP_COMPOSITOR=/path/to/mango MANGO_MCP_LIVE=1 python -m pytest # against another mangoLogs: ~/.local/state/mango-mcp/server.log; per-desktop mango.log,
dbus.log and per-app logs live in the desktop's runtime directory while it
runs.
This server cannot be deployed
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
Persistent Linux computers for AI agents: desktop, signed-in browser, vault, apps and shell.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.