Skip to main content
Glama
kuhyx

i3wm-mcp

by kuhyx
OverviewSchemaRelated ServersScoreDiscussions
Python

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.

Related MCP server: Tmux MCP Server

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.

Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • Tmux MCP Server

    audibleblink
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.
    16
    14
    Do What The F*ck You Want To Public

  • FVWM3 Window Manager

    elsanchez
    F
    license
    -
    quality
    -
    maintenance
    Enables interaction with the FVWM3 window manager for configuration generation, window management, and debugging. Provides access to config files, runtime state, and control tools for managing desktops, monitors, and tiling operations.

  • tmux-mcp

    WENLIXIAO-CS
    A
    license
    A
    quality
    D
    maintenance
    Allows AI assistants to create, manage, and interact with tmux sessions, windows, and panes programmatically.
    19
    MIT

View all related MCP servers

Related MCP Connectors

  • SentinelX

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

  • Astravue MCP

    Manage projects, tasks, time tracking, and team collaboration through natural language.

  • APICK AI

    LLM chat, text summarization and AI image generation

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kuhyx/i3wm-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server