lowcache/mcp-box
GitHub: lowcache/mcp-box
一个用 Go 编写的 CLI 工具，为 MCP server 提供严格隔离的 Docker 容器沙箱，保障 AI 代理工具调用的安全性。
Stars: 1 | Forks: 0
# mcp-box
[](https://github.com/lowcache/mcp-box/actions/workflows/ci.yml)
[](LICENSE)
[](src/go/go.mod)
**你的 AI 代理工具在你的权限下运行。** 当一个 MCP server 可以调用 `run_command` 或写入文件时，
一个有缺陷的 prompt 或一条恶意的指令可能会触及你的主目录、你的 SSH 密钥以及你的云凭据。
`mcp-box` 将每个 MCP server 放置在一个锁定的 Docker 沙箱中，具有只读的根文件系统、显式可写挂载、
丢弃的 Linux capabilities 以及基于 profile 的网络策略。只有你挂载的文件夹是可写的；主机的其余部分将无法触及。
**mcp-box** 是一个单一、可移植的 **Go** 二进制文件，可为 Model Context Protocol (MCP) server 启动交钥匙、不可变、严格隔离的
容器沙箱。如果存在 Nix，它将用于确定性的镜像构建，但它**完全是可选的**。如果没有 Nix，`mcp-box` 会从 GHCR 拉取相同的固定 OCI 镜像定义
，并在相同的 Docker 隔离模型下运行它们。Docker 是唯一的硬性要求。
## 安全审计检查
你可以通过使用 -- bash -c '...' 覆盖容器命令来直接审计沙箱边界。
这些检查证明了边界本身，而不仅仅是在其内部运行的 MCP server。
加固（只读根目录、无网络、丢弃 capabilities、主机 UID 映射）适用于 box 内的*任何*进程：
1. **只读文件系统** — `/workspace` 之外的写入操作将被拒绝：
./mcp-box run shell -- bash -c 'touch /etc/naughty'
# => touch: cannot touch '/etc/naughty': Read-only file system (exit 1)
2. **网络隔离** — 使用默认的 `--network none` 时，DNS/egress 会失败：
./mcp-box run shell -- bash -c 'curl -I https://google.com'
# => curl: (6) Could not resolve host: google.com (exit 6)
3. **无权限提升** — 镜像中甚至不存在 `sudo`：
./mcp-box run shell -- bash -c 'sudo -l'
# => bash: line 1: sudo: command not found (exit 127)
4. **主机 UID/GID 映射** — 进程是*你*，而不是 root：
./mcp-box run shell -- bash -c 'id'
# => uid= gid= ... (/workspace 中的文件由你拥有)
## 主要功能
1. **严格沙箱化**：
- **不可变根目录 (`--read-only`)**：整个根文件系统以只读方式挂载。
- **临时状态 (`--tmpfs`)**：可写空间（`/tmp` 和 `/run`）仅存在于 RAM 中，并在容器停止后消失。
- **零 capabilities (`--cap-drop=ALL`)**：正在运行的进程没有特殊的 Linux 内核 capabilities。
- **无权限提升 (`no-new-privileges:true`)**：防止在沙箱内提升到 root。
- **基于 profile 的网络策略**：
- 大多数沙箱默认为 `--network none`。
- 带有网络配置的 profile 是显式且可选的，因此只有当 server 的工作确实需要时才会获得 egress 权限。
- `fetch` profile 是设计上的例外：它使用受控的网络模式进行 Web 访问，同时仍保持容器边界完好无损。
- **作用域工作区**：只有特定挂载的主机目录 (`--workspace`) 在 `/workspace` 路径下对 server 可见。
2. **正确的文件所有权**：
- 容器运行时映射到你的主机 UID/GID (`-u $(id -u):$(id -g)`)，确保写入挂载工作区的文件归你所有（而不是 `root`），并且不会触发主机端的权限错误。
3. **无痛集成**：
- 内置配置生成器 (`mcp-box config `) 可打印出可直接粘贴的 JSON 片段，以便直接插入 `claude_desktop_config.json` 或 OpenClaw 配置中。
4. **零依赖的 Nix 自主性**：
- 如果安装了 Nix，运行沙箱会自动触发 OCI 镜像的本地重建和加载。
- 如果没有 Nix，`mcp-box` 会自动检测到这一点，并回退到直接从 GitHub Container Registry (`ghcr.io/lowcache`) 拉取预构建的、完全相同且安全的 OCI 镜像，这使得 Nix 对最终用户来说完全是可选的。
## CLI 接口
`mcp-box` 旨在可检查、可脚本化和可审计。
- `mcp-box run ` — 启动一个沙箱化的 MCP server
- `mcp-box stop ` — 停止正在运行的沙箱
- `mcp-box ps` — 列出活动沙箱
- `mcp-box inspect ` — 显示完整的沙箱规范和策略
- `mcp-box logs ` — 读取审计日志
- `mcp-box logs --follow` — 流式传输实时事件
- `mcp-box config ` — 打印可直接粘贴的客户端配置
- `mcp-box build ` — 重建或刷新 OCI 镜像
## 快速开始
```
# 1. 获取 binary（Docker 是唯一的 dependency）
curl -sSL https://github.com/lowcache/mcp-box/releases/latest/download/mcp-box-linux-amd64 -o mcp-box
chmod +x mcp-box && mv mcp-box ~/.local/bin/
# 2. 证明 sandbox 有效 — 这次 write 必定失败
mcp-box run shell --workspace /tmp/demo -- bash -c 'touch /etc/naughty'
# => touch: cannot touch '/etc/naughty': Read-only file system
# 3. 将其接入你的 AI client（将输出粘贴到 claude_desktop_config.json 中）
mcp-box config sqlite
```
## 预打包的沙箱
| Server 名称 | 语言 | 包含的实用工具 | 网络模式 | 主要用途 |
| :--- | :--- | :--- | :--- | :--- |
| **`sqlite`** | Python | `sqlite3` CLI, `fastmcp` SDK | `none` | 高性能、隔离的数据库查询。 |
| **`shell`** | Python | `bash`, `ripgrep`, `fd`, `git`, `curl`, `jq`, `sqlite`, `tar` | `none` | 安全、沙箱化的脚本运行和文件操作。 |
| **`filesystem`** | Node.js | `ripgrep`, `fd`, `git` | `none` | 作用域内的文件系统读写和代码搜索。 |
| **`fetch`** | Node.js | `curl` | `bridge` | 安全、隔离的 Web 抓取和爬取。 |
## 策略、组合与可审计性
`mcp-box` 不仅是一个运行器 —— 它是 MCP 执行的信任层。
计划的核心平台功能：
- 针对常见信任级别的**策略 profile**：`readonly`, `dev`, `trusted`, `internet-off`, `internet-on`
- 用于多服务器设置的**组合式规范**
- 用于沙箱生命周期和拒绝操作的**仅追加审计日志**
- **`ps` / `inspect` / `logs`** 以便每个沙箱在启动后都可以进行检查
- **固定的镜像摘要** 以实现可重现、可审查的执行
## 依赖项
根据你的安装路径，`mcp-box` 有不同的依赖要求：
* **运行时边界（所有用户）**：
- **Docker Engine**（必须在主机系统上本地激活并运行）。
* **本地镜像构建（使用 Nix 的源码流）**：
- **Nix**（需启用实验性的 `flakes` 和 `nix-command`）。
* **CLI 编译（使用 Go 的源码流）**：
- **Go** 编译器 v1.22 或更高版本（仅在不使用 Nix 从源码构建可执行文件时需要）。
* **零依赖回退流程**：
- **无**。预编译的 CLI 二进制文件可独立运行，并自动将预构建的多架构 OCI 镜像直接从 GHCR 拉取到你本地的 Docker daemon 中。
## 架构
```
graph TD
subgraph Host [Host Environment]
Agent[AI Agent / Claude Desktop] <-->|stdio piping| CLI[mcp-box CLI]
CLI -->|Checks for Nix| NixDetect{Nix Installed?}
NixDetect -->|Yes: Source Flow| NixBuild[nix build .#server]
NixBuild -->|Stream tarball| DockerLoad[docker load]
NixDetect -->|No: Registry Flow| DockerPull[docker pull ghcr.io]
DockerPull -->|Tag locally| DockerLoad
DockerLoad -->|Loads image| Docker[Docker Engine]
end
subgraph Sandbox [Docker Sandbox]
Server[MCP Server]
Tools[Isolated Tools: git, rg, sqlite3, curl]
Workspace[Mounted Workspace: /workspace]
end
Docker -->|spawns with strict isolation| Sandbox
CLI <-->|stdio piping| Server
```
## 安装
根据你的主机环境，你可以通过三种不同的途径安装和运行 `mcp-box`：
### 选项 A：预构建的 Go 二进制文件（无 Nix / 仅限 Docker）
对于仅安装了 Docker 的系统：
1. **下载已编译的 CLI 二进制文件**（选择与你的 OS/架构匹配的资产 —— `linux`/`darwin`, `amd64`/`arm64`）：
curl -sSL https://github.com/lowcache/mcp-box/releases/latest/download/mcp-box-linux-amd64 -o mcp-box
chmod +x mcp-box
2. **移动到 PATH**（可选）：
mv mcp-box ~/.local/bin/ # Or another folder in your PATH
*首次执行时，`mcp-box` 会自动检测到 Nix 的缺失，并将预构建的 OCI 镜像从 `ghcr.io/lowcache` 拉取到你本地的 Docker daemon 中。*
### 选项 B：通过 Nix Flake 从源码安装（Nix/NixOS）
对于运行 Nix/NixOS 的系统：
* **直接运行而无需安装**：
nix run github:lowcache/mcp-box -- list
* **安装到你的用户 profile**：
nix profile install github:lowcache/mcp-box
* **声明式安装（NixOS / Home Manager）**：
将 flake 输入和 package 添加到你的配置中：
# flake.nix inputs：
inputs.mcp-box.url = "github:lowcache/mcp-box";
# 在 systemPackages 或 home.packages 中：
inputs.mcp-box.packages.${pkgs.system}.default
*首次执行时，`mcp-box` 将完全从源码构建 Go 二进制文件和 OCI 镜像，并将它们直接加载到你本地的 Docker daemon 中。*
### 选项 C：从源码编译（Go 编译器）
如果你想在不用 Nix 的情况下手动编译 CLI 二进制文件：
1. **克隆仓库**：
git clone https://github.com/lowcache/mcp-box.git
cd mcp-box
2. **编译二进制文件**（Go 模块位于 `src/go` 中）：
cd src/go
go build -o ../../mcp-box .
*你现在可以直接运行 `./mcp-box`，它会根据你的主机环境从 registry 拉取 OCI 层，或者使用 Nix 在本地构建。*
## 使用指南
### 1. 显示帮助和支持的 server
```
./mcp-box help
./mcp-box list
```
### 2. 交互式运行沙箱
你可以交互式地启动任何 server，以测试其行为和工具：
```
./mcp-box run sqlite --workspace /tmp/sandbox-db -- --db /workspace/test.db
```
### 3. 构建/强制更新 OCI 镜像
如果你想手动重建或强制更新基于 Nix 构建的镜像：
```
./mcp-box build sqlite
```
### 4. 与 AI 客户端集成
`mcp-box config ` 会打印出一个可直接粘贴的 `mcpServers` JSON 块（包含
二进制文件的绝对路径）。相同的块适用于 Claude Desktop 和
Claude Code。
```
./mcp-box config sqlite
```
#### Claude Code (CLI)
Claude Code **不**使用 `claude_desktop_config.json`。使用一条命令添加 server —— 注意嵌套的 `--`（第一个用于将 `claude` 的标志与
子进程分开；第二个由 `mcp-box` 消耗以转发 server 参数）：
```
# user scope（在每个项目中可用；去掉 -s user 仅用于当前项目）
claude mcp add -s user mcp-box-sqlite -- \
mcp-box run sqlite --workspace /abs/path/to/workspace -- --db /workspace/db.sqlite
```
或者，要将可共享的配置提交到你的仓库，请将 `mcp-box config` 的 JSON 块
直接放入项目根目录的 **`.mcp.json`** 中 —— 它使用与 `config` 输出的完全相同的 `{"mcpServers": …}`
结构。
使用 `claude mcp list` 进行验证。
#### Claude Desktop
将 `config` 块粘贴到 `claude_desktop_config.json` 中。其位置
特定于操作系统：
| 操作系统 | 路径 |
| :--- | :--- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
标签：AI智能体, Docker, EVTX分析, Go语言, MCP服务器, MITM代理, 安全防御评估, 安全隔离, 容器沙箱, 日志审计, 程序破解, 请求拦截, 逆向工具