Ubuntu MCP

Ubuntu MCP——Ubuntu命令服务器（Docker化）

该项目提供了一个基于Ubuntu的小型容器，该容器公开了一个安全的HTTP API来在容器内执行shell命令。它还包括在stdio模式下运行时使用FastMCP的MCP（模型上下文协议）工具定义。默认情况下，Docker镜像服务于端口9000上带有FastAPI/Uvicorn的HTTP API。

这里的目标是为其他人工智能提供一个沙盒，让它们在不改变系统的情况下运行本地代码。

内容：

• Ubuntu 22.04基础镜像
• 使用FastAPI、Uvicorn和FastMCP的Python 3
• HTTP端点：

- 获取 /health --健康检查 - 发布 /api/exec --在容器中执行命令并返回 returncode, stdout, stderr

• 运行时可选的FastMCP工具 server.py 直接（stdio传输）

先决条件

• Docker（推荐）
• curl（用于快速测试）
• jq（可选，用于在示例中漂亮地打印JSON）

快速入门（Docker）

1. 构建镜像（苹果Silicon/ARM用户：该项目将linux/amd64固定为兼容性）：

docker build --platform linux/amd64 -t frkr/ubuntu-mcp:22.04 .

1. 运行容器，将当前目录装载到 /home/mcpuser 并暴露端口9000：

docker run --platform linux/amd64 \
  -v "$(pwd)":/home/mcpuser \
  --rm -d --name frkr/ubuntu-mcp \
  -p 9000:9000 \
  frkr/ubuntu-mcp:22.04

1. 检查健康状况：

curl -s http://localhost:9000/health
# {"status":"ok"}

1. 通过HTTP执行命令：

curl -s -X POST http://localhost:9000/api/exec \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}' | jq .

停止并移除容器：

docker rm -f ubuntu-mcp

单行运行（当前目录）：

docker run --platform linux/amd64 -v"$(pwd)":/home/mcpuser --rm -d --name ubuntu-mcp -p 9000:9000 frkr/ubuntu-mcp:22.04

api参考

• 获取 /health

- 答复： { "status": "ok" }

• 发布 /api/exec

- 请求JSON：

    { "command": "ls -la" }

- 响应JSON（示例）：

    {
      "returncode": 0,
      "stdout": "total 0\n-rw-r--r-- 1 mcpuser mcpuser 0 Dec  1 00:00 example.txt\n",
      "stderr": null
    }

- 笔记： - 命令运行超时30秒；在超时时， returncode 将是 124 和 stderr 将描述超时时间。 - 工作目录为 /home/mcpuser （示例中安装了您的卷）。

演示脚本

有一个助手脚本，用于构建映像、运行容器、等待就绪、调用API、打印日志和清理：

./test.sh

MCP集成说明

• 包括 mcp.json 是演示将客户端/工具层指向HTTP exec端点的最小映射：

  {
    "mcpServers": {
      "ubuntu_mcp": {
        "description": "Ubuntu Command Server, its only way to execute commands because of security.",
        "url": "http://localhost:9000/api/exec"
      }
    }
  }

• server.py 定义了几个FastMCP工具(execute_command, list_directory, get_current_directory, get_system_info).在stdio模式下运行时，这些功能可用(python3 server.py).当通过HTTP（Uvicorn）提供服务时，您通过上面描述的REST API进行交互。
• Deno的一个小例子在 testdeno.ts 该POST发送到HTTP API：

  deno run --allow-net testdeno.ts

安全注意事项

• 这 /api/exec 端点执行客户端发送的任意shell命令。
• 不要将此服务暴露给不受信任的网络。
• 更喜欢在一次性容器内运行，如图所示。
• 容器使用非root用户(mcpuser)，但这并不能消除风险。

故障排除

• 端口已在使用中：更改 -p 9000:9000 到另一个主机端口。
• Apple Silicon（ARM64）主机：示例说明 --platform linux/amd64。如果为ARM本地构建/运行，则可以省略它，但要确保基础/映像兼容性。
• 卷权限：如果你看不到容器内的文件，请检查你挂载的路径和权限。在Windows上，调整 -v 相应的路径语法。

许可证

麻省理工学院——见 许可证.