AI导哈

命令行执行服务

通过HTTP传输执行任意Shell命令的MCP服务器，专为需要在本地机器或容器内运行命令的AI代理设计。

  • by MrMarCode
  • Shell
  • 本地部署
  • 更新于
在 GitHub 查看 MrMarCode/run-box

使用说明

跑步箱

通过HTTP传输执行任意shell命令的MCP服务器。专为需要在本地机器或容器内运行命令的AI代理而设计。守护进程在可配置端口上监听，并通过Streamable HTTP和SSE流式传输为MCP协议提供服务。

快速开始

使用 start-run-box.sh

# Build the image
./build.sh

# Start with a single mount directory
./start-run-box.sh /home/user/Code

# Start with multiple mount directories (comma-separated)
./start-run-box.sh /home/user/Code,/home/user/Documents

# Force-restart a running instance on a custom port
./start-run-box.sh -f /home/user/Code 3200

# Verify
curl http://127.0.0.1:3100/health
# {"status":"ok"}

直接使用podman

Docker可以用来代替podman——命令是相同的。

# Build the image
./build.sh

# Mount host dirs to the SAME absolute path inside the container
# so the model sees identical paths
podman run --rm -p 3100:3100 \
   -v /home/user/Code:/home/user/Code \
   localhost/run-box

# Verify
curl http://127.0.0.1:3100/health
# {"status":"ok"}

MCP客户端配置

{
   "mcpServers": {
      "run-box": {
         "url": "http://127.0.0.1:3100/mcp"
      }
   }
}

工具： execute

在中运行shell命令 /bin/sh 并返回stdout、stderr和退出代码。

参数 类型 必填 说明
command string ✅ 要执行的Shell命令
cwd string ❌ 工作目录（绝对路径）
timeout 编号 ❌ 超时（毫秒）（1000–3600000）

环境变量

变量 默认值 描述
PORT 3100 要侦听的TCP端口
HOST 127.0.0.1 绑定地址
DEFAULT_CWD /workspace 默认工作目录
DEFAULT_TIMEOUT_MS 300000 默认超时（5分钟）
MAX_OUTPUT_BYTES 10485760 每个命令的最大输出（10 MB）
SHUTDOWN_GRACE_MS 5000 SIGKILL关闭前的宽限期

测试

npm test              # all tests
npm run test:unit     # unit tests only
npm run test:integration  # integration tests only

特性

  • HTTP传输：用于并发MCP客户端的流式HTTP和SSE流式传输
  • 执行命令：运行任何shell命令并获取stdout、stderr、exit代码
  • 流媒体：长时间运行的命令的进度通知（通过 _meta.progressToken)
  • 取消：通过MCP取消飞行中的命令 notifications/cancelled
  • 超时：可配置每个命令超时，并自动终止进程
  • 输出限制：可配置的最大输出大小，带截断指示器
  • 容器：使用开发工具（git、curl、build essential）的多阶段Dockerfile
  • 卷装载：将主机目录装载到容器中 /workspace
  • 平滑关闭：SIGTERM/SIGINT处理和进程清理
  • 健康检查: GET /health 管弦乐器端点

相关 MCP