# shell-use

> shell-use is an open-source MCP server for developer tools. MCP server that lets AI agents drive tmux shell sessions like a human terminal user. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/kyuheon-kr/shell-use
- **MCP Registry name:** io.github.kyuheon-kr/shell-use
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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

## 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.

## Alternatives

- [tmux](https://ai-powered.com/mcp/tmux): tmux is an open-source MCP server for developer tools.
- [terminal-use](https://ai-powered.com/mcp/terminal-use): terminal-use is an open-source MCP server for developer tools.
- [Unterm](https://ai-powered.com/mcp/unterm): Unterm is an open-source MCP server for developer tools.
- [MCP Ssh Manager](https://ai-powered.com/mcp/mcp-ssh-manager): MCP Ssh Manager is an open-source MCP server for developer tools.
- [agent-manager.dev documentation](https://ai-powered.com/mcp/agent-manager-dev-documentation): agent-manager.dev documentation is an open-source MCP server for developer tools.
- [MCP Server Commands](https://ai-powered.com/mcp/mcp-server-commands): MCP Server Commands is an open-source MCP server for developer tools.
- [Sshboard](https://ai-powered.com/mcp/sshboard): Sshboard is an MCP server for developer tools.
- [Coding Tools MCP](https://ai-powered.com/mcp/coding-tools-mcp): Coding Tools MCP is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/shell-use
