shell-use
Provides tools to interact with tmux sessions, allowing AI agents to send keystrokes, capture terminal output, and scroll through history, enabling interaction with any CLI application.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shell-use In the dev session, open vim and insert 'foo' at line 3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Returns allowed session names |
| Captures terminal screen text |
| Sends key input (e.g., |
| Sends literal text ( |
| Scrolls through history |
| Exits copy-mode |
Setup
1. Build the Docker image
docker build -t shell-use:latest .2. Create a tmux session
tmux new-session -s dev2.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:latestClaude 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/defaultwith the path fromtmux display-message -p -F '#{socket_path}'.
Environment Variables
Variable | Description | Required |
| Comma-separated list of allowed session names | Yes |
| Path to tmux socket (default: | No |
Acknowledgments
Inspired by browser-use.
Available Tools
6 toolscaptureC
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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Docs for agent-manager, the terminal UI that runs AI coding agents as live tmux sessions.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to spawn, interact with, and orchestrate multiple concurrent terminal sessions via tmux.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to execute commands in a shared tmux session that is simultaneously visible to a human via a web-based terminal UI.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with interactive CLI processes via a real PTY, allowing them to send keystrokes, read screen output, and handle interactive prompts.6 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT