shell-use

Name: shell-use
Author: kyuheon-kr

本地服务

github.com/kyuheon-kr开发工具040 周前更新

代码仓库

关于 shell-use

shell-use 是一个 MCP 服务，让 Agent 通过 tmux 会话操作交互式命令行应用。它提供终端内容捕获、键盘输入和滚动功能，并支持通过 Docker 部署。

主要功能

01操作命令行应用
02捕获终端屏幕文本
03发送按键和文本
04滚动查看终端历史
05限制可访问的会话名称

适用场景

01让 Agent 操作交互式命令行
02检查 tmux 会话中的输出
03向运行中的进程发送键盘命令

MCP 相关

MCP 服务提供列出允许的会话、捕获终端文本、发送按键或文本以及滚动会话历史等工具。它通过 socket 连接 tmux，并在 MCP 客户端中配置。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "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>"
      }
    }
  }
}

启动命令docker run -i --rm -e SHELL_USE_SESSIONS -e SHELL_USE_SOCKET ghcr.io/kyuheon-kr/shell-use:1.0.0

需要配置的环境变量

SHELL_USE_SESSIONSComma-separated list of allowed session names

SHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

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

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

shell-use

让 Agent 像人一样使用 shell。

功能

与任意 CLI 应用交互（vim、htop、gdb 等）
发送特殊按键（Ctrl+C、Enter、方向键等）
使用 Docker 封装，便于部署

可用工具

工具	描述
`list_sessions()`	返回允许使用的会话名称
`capture(session, scroll_back?)`	捕获终端屏幕文本
`send_keys(session, keys)`	发送按键输入（例如 `Enter`、`C-c`）
`send_text(session, text, enter?)`	发送纯文本（设置 `enter=True` 可按下 Enter）
`scroll(session, direction, amount?)`	滚动浏览历史记录
`exit_scroll_mode(session)`	退出复制模式

设置

1. 构建 Docker 镜像

docker build -t shell-use:latest .

2. 创建 tmux 会话

tmux new-session -s dev

2.1. 获取 tmux 套接字路径

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

3. 配置 MCP 客户端

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"
      ]
    }
  }
}

将 /tmp/tmux-1000/default 替换为以下命令返回的路径： tmux display-message -p -F '#{socket_path}'。

环境变量

变量	描述	必需
`SHELL_USE_SESSIONS`	允许使用的会话名称列表，以逗号分隔	是
`SHELL_USE_SOCKET`	tmux 套接字路径（Docker 中默认为 `/tmux/tmux.sock`）	否