i3wm-mcp

A Model Context Protocol server for the i3 window manager (and, via the shared IPC, Sway). It lets an MCP client — Claude Code, Claude Desktop, the MCP Inspector — query and drive your i3/Sway session through a small set of well-described tools.

The tool definitions are deliberately tuned for a high Glama tool-definition-quality score: a consolidated, non-overlapping tool set, every parameter described, typed output schemas, and honest readOnlyHint/destructiveHint annotations.

Derived from caninja/i3wm-mcp (MIT). See ATTRIBUTION.md. This rewrite migrates the transport from the i3-msg CLI to the async i3ipc library, consolidates 43 tools into 13, and adds tests, CI, and output schemas.

Tools

Tool	Kind	What it does
get_tree	read	List windows from the layout tree, with filters.
get_focused	read	Details of the currently focused window.
list_workspaces	read	All active workspaces.
list_outputs	read	All display outputs (monitors).
get_config	read	Version + config + binding modes snapshot.
focus_window	mutate	Focus by direction / criteria / layer / parent-child.
move_window	mutate	Move a container to a direction / workspace / output / scratchpad / center.
manage_workspace	mutate	Switch / move-to / rename / navigate workspaces.
set_layout	mutate	Container layout, split orientation, border style.
toggle_window_state	mutate	Toggle floating / fullscreen / sticky.
exec_application	destructive	Launch a program via i3 exec (arbitrary code).
run_command	destructive	Raw i3/Sway command escape hatch (marks, gaps, bar, reload/restart).
kill_window	destructive	Close the focused or a matched window.

Rarely-used verbs (marks, i3-gaps, i3bar, scratchpad show/hide, reload, restart, and deliberately exit) are reached through run_command rather than dedicated tools, keeping the set small and distinct.

Requirements

• A running i3 (≥4.x) or Sway session.
• Python ≥ 3.10.

The server locates the i3/Sway IPC socket from the environment, so it must be launched from within your graphical session (it needs DISPLAY, or SWAYSOCK/I3SOCK, in its environment). Clients that spawn it from inside the session — Claude Code, the MCP Inspector — inherit this automatically; a headless or systemd launch would need those variables passed explicitly.

Install

git clone https://github.com/kuhyx/i3wm-mcp
cd i3wm-mcp
python -m venv .venv
./.venv/bin/python -m pip install -e ".[dev]"

Run

./.venv/bin/python -m i3wm_mcp        # stdio transport

Register with Claude Code

claude mcp add i3wm -- /absolute/path/to/i3wm-mcp/.venv/bin/python -m i3wm_mcp

Inspect the tool definitions

npx @modelcontextprotocol/inspector ./.venv/bin/python -m i3wm_mcp

Develop

./.venv/bin/python -m pytest        # tests + 100% coverage gate
./.venv/bin/ruff check . && ./.venv/bin/ruff format --check .
./.venv/bin/mypy src
./.venv/bin/python scripts/rubric_check.py   # local TDQS proxy check

Safety

Read tools have no side effects. Mutation tools are reversible. The three destructive tools (exec_application, run_command, kill_window) can run arbitrary commands, close applications, or — via run_command — restart or exit the session; treat them accordingly and never feed them untrusted input.

License

MIT — see LICENSE.