mcpField
S
shell-use

shell-use

Local
github.com/kyuheon-krDeveloper Tools0Updated 40w ago
Repository

About shell-use

shell-use is an MCP server that lets agents operate interactive CLI applications through tmux sessions. It provides terminal capture, keyboard input, and scrolling, and is packaged for Docker deployment.

Key features

  1. 01Interact with CLI applications
  2. 02Capture terminal screen text
  3. 03Send keys and literal text
  4. 04Scroll through terminal history
  5. 05Restrict access to named sessions

Use cases

  1. 01Operate an interactive CLI from an agent
  2. 02Inspect output in a tmux session
  3. 03Send keyboard commands to a running process

MCP support

The MCP server exposes tools to list allowed sessions, capture terminal text, send keys or text, and scroll session history. It connects to tmux through a socket and is configured in an MCP client.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "kyuheon-kr-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": "<SHELL_USE_SESSIONS>",
        "SHELL_USE_SOCKET": "<SHELL_USE_SOCKET>"
      }
    }
  }
}
Run commanddocker run -i --rm -e SHELL_USE_SESSIONS -e SHELL_USE_SOCKET ghcr.io/kyuheon-kr/shell-use:1.0.0
Environment variables to set
SHELL_USE_SESSIONSComma-separated list of allowed session names
SHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
ocighcr.io/kyuheon-kr/shell-use:1.0.0

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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
ToolDescription
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
VariableDescriptionRequired
SHELL_USE_SESSIONSComma-separated list of allowed session namesYes
SHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)No
Acknowledgments

Inspired by browser-use.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.