Skip to main content
Glama
shell-use

shell-use

by kyuheon-kr

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.

Available Tools

6 tools
captureC

Captures current terminal screen text.

Inputs: session (required), scroll_back. Returns: result

exit_scroll_modeA

Exits tmux copy-mode and returns to normal mode.

Inputs: session (required). Returns: result

list_sessionsA

Returns list of available tmux sessions.

Inputs: no named parameters. Returns: result

scrollA

Navigates the scrollback buffer (half-pages by default).

Inputs: session (required), direction (required), amount. Returns: result

send_keysC

Sends key input. Supports tmux key notation (Enter, C-c, etc.).

Inputs: keys (required), session (required). Returns: result

send_textA

Sends literal text via tmux buffer. Supports multiline text with \n and \t.

Use enter=True for shell commands - automatically presses Enter after sending. Use enter=False (default) for editors - newlines are preserved as text.

Examples: - Shell: send_text(session, "ls -la", enter=True) -> executes command - Editor: send_text(session, "line1\nline2") -> pastes two lines

Inputs: text (required), session (required), enter. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: listing sessions, capturing output, sending key input, sending text, scrolling, and exiting scroll mode. While send_keys and send_text both handle input, their descriptions clearly differentiate key notation from literal text, and scroll/exiting scroll are complementary rather than overlapping.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (list_sessions, send_keys, send_text, exit_scroll_mode), but capture and scroll are single verbs. This is a minor deviation; the naming remains predictable and readable.

    Tool Count5/5

    With 6 tools, the server is well-scoped for its purpose of interacting with tmux sessions. Each tool covers a necessary operation—listing, capturing, sending, scrolling—without unnecessary redundancy.

    Completeness4/5

    The tool set covers the core lifecycle of terminal interaction: list sessions, send input, capture output, and navigate history. It lacks session creation or pane management, but these are outside the stated purpose of 'shell-use', so only minor gaps exist.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to execute commands in a shared tmux session that is simultaneously visible to a human via a web-based terminal UI.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to spawn persistent terminal sessions, send keystrokes, read screen state, and assert output, allowing them to interact with stateful terminal applications like vim, htop, and gdb.
      54 npm
      MIT