Shell Use

What shell-use MCP server does

The shell-use MCP server gives an MCP-compatible agent access to selected tmux sessions. Instead of treating the terminal as a one-shot command interface, it exposes the visible terminal state and accepts keyboard-style input. This allows an agent to interact with full-screen and stateful command-line programs, including vim, htop, and gdb.

Access is restricted to session names supplied through SHELL_USE_SESSIONS. The server can work with more than one permitted session when their names are provided as a comma-separated list.

How it works

The server communicates with tmux through a Unix socket. A tmux session must already exist, and the socket used by that tmux instance must be made available to the container when running the Docker image.

Agents can request the available session names, read the current terminal screen, and provide input. Text can be sent literally, optionally followed by Enter. Key-oriented input supports values such as Enter and C-c, along with arrow keys and other special keys. Scroll operations expose terminal history, while a separate operation leaves copy mode.

The shell-use MCP server is therefore suited to workflows where the agent needs to observe an evolving terminal and respond to it incrementally. It does not describe a general remote shell or a collection of independent command-execution tools; its documented interface is centered on tmux sessions and terminal interaction.

Setup and configuration

Build the image from the repository with:

docker build -t shell-use:latest .

Create a tmux session, such as dev, then obtain its socket path with tmux display-message -p -F '#{socket_path}'. The path should point to an existing socket before starting the container.

Run the container with the socket mounted at /tmux/tmux.sock. Set SHELL_USE_SOCKET to that in-container path and set SHELL_USE_SESSIONS to the permitted session name, for example dev. The socket variable is optional because the Docker default is /tmux/tmux.sock; the session-list variable is required.

The README provides configuration examples for Claude Code and Claude Desktop. The Claude Code example registers the server through claude mcp add; the Claude Desktop example adds a docker run command to claude_desktop_config.json. In either case, replace the example host socket path with the path reported by tmux.

Tools and capabilities

The documented tools are:

• list_sessions() returns the allowed session names.
• capture(session, scroll_back?) reads terminal screen text, with optional scrollback.
• send_keys(session, keys) sends key input such as Enter or C-c.
• send_text(session, text, enter?) sends literal text and can press Enter afterward.
• scroll(session, direction, amount?) moves through terminal history.
• exit_scroll_mode(session) leaves copy mode.

Together, these operations cover screen inspection, literal input, special-key input, and terminal-history navigation for the permitted tmux sessions.

Limitations and notes

A tmux session and an accessible tmux socket are prerequisites. The server only exposes sessions allowed by SHELL_USE_SESSIONS, so a session omitted from that list is not part of the documented access scope. Docker deployment also requires mounting the host socket into the container.

It also does not specify behavior for detached sessions, multiple tmux servers, or command failures beyond the listed tool operations.