mcp server

shell-use

Let agents use the shell like a human.

kyuheon-kr/shell-usecommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Docker Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

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

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

shell-use

Let agents use the shell like a human.

Features

Interact with any CLI application (vim, htop, gdb, etc.)
Send special keys (Ctrl+C, Enter, arrow keys, etc.)
Dockerized for easy deployment

Available Tools

Tool	Description
`list_sessions()`	Returns allowed session names
`capture(session, scroll_back?)`	Captures terminal screen text
`send_keys(session, keys)`	Sends key input (e.g., `Enter`, `C-c`)
`send_text(session, text, enter?)`	Sends literal text (`enter=True` to press Enter)
`scroll(session, direction, amount?)`	Scrolls through history
`exit_scroll_mode(session)`	Exits copy-mode

Setup

1. Build the Docker image

docker build -t shell-use:latest .

2. Create a tmux session

tmux new-session -s dev

2.1. Get the tmux socket path

SOCK="$(tmux display-message -p -F '#{socket_path}')"
[ -S "$SOCK" ] || { echo "tmux socket not found: $SOCK"; exit 1; }

3. Configure your MCP client

Claude Code:

claude mcp add shell-use \
  -- docker run -i --rm \
  -v "$SOCK":/tmux/tmux.sock \
  -e SHELL_USE_SOCKET=/tmux/tmux.sock \
  -e SHELL_USE_SESSIONS=dev \
  shell-use:latest

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shell-use": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/tmp/tmux-1000/default:/tmux/tmux.sock",
        "-e", "SHELL_USE_SOCKET=/tmux/tmux.sock",
        "-e", "SHELL_USE_SESSIONS=dev",
        "shell-use:latest"
      ]
    }
  }
}

Replace /tmp/tmux-1000/default with the path from tmux display-message -p -F '#{socket_path}'.

Environment Variables

Variable	Description	Required
`SHELL_USE_SESSIONS`	Comma-separated list of allowed session names	Yes
`SHELL_USE_SOCKET`	Path to tmux socket (default: `/tmux/tmux.sock` in Docker)	No

Acknowledgments

Inspired by browser-use.