shell-use
MCP server that lets AI agents drive tmux shell sessions like a human terminal user
- Pricing
- Open source
- Platforms
- CLI, self-hosted
- Runs
- Locally
- Version
- 1.0.0
- Listing updated
- today
Similar MCP servers
About shell-use
shell-use is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
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.
Install
Run in a 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.0Add to claude_desktop_config.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>"
}
}
}
}Add to ~/.cursor/mcp.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>"
}
}
}
}Add to .vscode/mcp.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>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.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>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"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>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
SHELL_USE_SESSIONSComma-separated list of allowed session namesRequiredSHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- 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
What it does
- 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
Pricing
Open source
shell-use 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.