Skip to content
MCP server

shell-use

MCP server that lets AI agents drive tmux shell sessions like a human terminal user

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
1.0.0
Listing updated
today

Similar MCP servers

About shell-use

shell-use is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

The server gives an agent a view of an existing tmux session: it can read the current screen, including scrollback, type literal text, and send control or navigation keys. Operators list the sessions an agent may touch through an environment variable, so the agent cannot reach sessions outside that allowlist.

The README says the approach works with interactive programs such as vim, htop and gdb, where the agent needs to read a screen and respond to it rather than run a one-shot command. Scrolling through history and leaving copy-mode are exposed as separate tools.

It is aimed at developers who want an agent to operate a terminal program alongside them, and who are comfortable running a tmux server and mounting its socket into a Docker container.

Install

Run in a terminal

claude mcp add shell-use --env SHELL_USE_SESSIONS='<SHELL_USE_SESSIONS>' -- docker run -i --rm -e SHELL_USE_SESSIONS ghcr.io/kyuheon-kr/shell-use:1.0.0

Add to claude_desktop_config.json

{
  "mcpServers": {
    "shell-use": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHELL_USE_SESSIONS",
        "ghcr.io/kyuheon-kr/shell-use:1.0.0"
      ],
      "env": {
        "SHELL_USE_SESSIONS": "<SHELL_USE_SESSIONS>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "shell-use": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHELL_USE_SESSIONS",
        "ghcr.io/kyuheon-kr/shell-use:1.0.0"
      ],
      "env": {
        "SHELL_USE_SESSIONS": "<SHELL_USE_SESSIONS>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "shell-use": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHELL_USE_SESSIONS",
        "ghcr.io/kyuheon-kr/shell-use:1.0.0"
      ],
      "env": {
        "SHELL_USE_SESSIONS": "<SHELL_USE_SESSIONS>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "shell-use": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHELL_USE_SESSIONS",
        "ghcr.io/kyuheon-kr/shell-use:1.0.0"
      ],
      "env": {
        "SHELL_USE_SESSIONS": "<SHELL_USE_SESSIONS>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "shell-use": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHELL_USE_SESSIONS",
        "ghcr.io/kyuheon-kr/shell-use:1.0.0"
      ],
      "env": {
        "SHELL_USE_SESSIONS": "<SHELL_USE_SESSIONS>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • SHELL_USE_SESSIONSComma-separated list of allowed session namesRequired
  • SHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)

Tools this server provides (6)

Taken from the project documentation; the running server may differ.

list_sessions
Returns allowed session names
capture
Captures terminal screen text
send_keys
Sends key input such as Enter or C-c
send_text
Sends literal text, optionally pressing Enter
scroll
Scrolls through history
exit_scroll_mode
Exits copy-mode

What it does

Screen capture
Reads the text currently shown in a tmux session, with optional scrollback.
Literal text input
Types text into a session and can press Enter afterwards.
Special key sending
Sends keys such as Enter, Ctrl+C and arrow keys to a session.
Scrollback navigation
Scrolls through terminal history and exits copy mode.
Session allowlist
Restricts the agent to session names set in an environment variable.
Docker deployment
Runs as a container that connects to a mounted tmux socket over stdio.

Good for

  • Letting an agent step through an interactive debugger such as gdb
  • Watching and responding to a long-running htop or log view in tmux
  • Driving a terminal editor like vim during a coding session
  • Running commands in a shared dev tmux session while an agent assists

Pricing

Open source

shell-use FAQ

Which sessions can the agent access?

Only the session names listed in SHELL_USE_SESSIONS, which is a required comma-separated variable.

How is the server started?

The README shows running the Docker image with stdio transport, mounting the tmux socket and setting the socket and session variables, for Claude Code or Claude Desktop.

Which tools does it expose?

list_sessions, capture, send_keys, send_text, scroll and exit_scroll_mode.

Is shell-use free?

Yes. shell-use is open source, so you can use and self-host it for free.

How do I add shell-use to Claude Code?

Run this command in your terminal: claude mcp add shell-use --env SHELL_USE_SESSIONS='<SHELL_USE_SESSIONS>' -- docker run -i --rm -e SHELL_USE_SESSIONS ghcr.io/kyuheon-kr/shell-use:1.0.0

What are the best alternatives to shell-use?

The closest alternatives to shell-use are tmux, terminal-use, Unterm, MCP Ssh Manager and agent-manager.dev documentation.

Where this comes from

  • Description: written from the project's README and its MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers