mcp-sandman
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-sandman
MCP 服务器的策略沙箱代理。
中文 | English
把 agent 的连接指向 mcp-sandman,而不是直接指向 MCP 服务器。工具列表、每一次
工具调用、每一个路径和主机名,都要先过一遍你写的策略;策略不允许的,在到达服务器
之前就被拒绝。
agent ──stdio──▶ mcp-sandman ──stdio──▶ 你的 MCP 服务器
│
├── 有哪些工具
├── 哪些路径可以读、可以写
├── 可以访问哪些主机
└── 每个决策写一行审计为什么需要它
你装了个第三方 MCP server,让 agent 能查数据库。但它同时也能 read_file——没人拦
着它。它拿着你的凭据,跑在你的 shell 里,你的 SSH 私钥就在旁边。
绝大多数 MCP 工具默认「server 可信、agent 不可信」。而这个假设恰好在你装了个没审 计过的包的时候失效。
mcp-sandman 把这个假设反过来:server 视为敌意,最终由策略决定它能做什么。
Related MCP server: mcp-policy-gateway
安装
从源码(推荐)
Rust 生态的标准装法,不需要任何额外权限:
cargo install --git https://github.com/xiaoy-ovo/mcp-sandman
# 或者手动:
git clone https://github.com/xiaoy-ovo/mcp-sandman
cd mcp-sandman && cargo build --release下载预编译二进制
每次发布 tag 都会自动构建六个平台的二进制:
平台 | 文件 |
Windows x86_64 / arm64 |
|
macOS Intel |
|
macOS Apple Silicon |
|
Linux x86_64 / arm64 |
|
从 Releases 页 下载对应文件,解压即用:
tar -xzf mcp-sandman-x86_64-apple-darwin.tar.gz
./mcp-sandman --versionnpm(Windows 最省事)
npm install -g mcp-sandmanWindows x86_64 的二进制直接打包在 npm 包里,装完即用。
macOS 和 Linux 上这个包不含二进制,postinstall 会提示你去源码编译——它选择警告而不是失败,因为 npm 包在 postinstall 阶段失败会留下无法恢复的 node_modules。
平台支持
平台 | 源码编译 | 预编译二进制 |
Windows x86_64 / arm64 | CI 验证通过 | ✅ |
macOS Intel / Apple Silicon | CI 验证通过 | ✅ |
Linux x86_64 / arm64(glibc) | CI 验证通过 | ✅ |
CI 在三个平台上都编译并跑测试;预编译二进制由 tag 触发的工作流产出。
两个实际会踩的坑:
Linux 版本链接的是 glibc。在 Alpine(musl)上需要源码编译并指定 musl target。
container隔离模式会调docker。macOS 和 Linux 都能用;Windows 上需要 Docker Desktop 的 Linux 后端——Windows 容器跑不了这些策略预设的 node 镜像。
使用
生成一份起步策略:
mcp-sandman init "npx -y @some/package" > sandman.toml看策略放行了哪些工具:
$ mcp-sandman --config sandman.toml doctor
2 tool(s) exposed:
read_file
fetch_url接进 agent 的 MCP 配置:
{
"mcpServers": {
"db": {
"command": "mcp-sandman",
"args": ["--config", "/path/to/sandman.toml"]
}
}
}用 npm 包的话,npx mcp-sandman 写法一样:
{
"mcpServers": {
"db": {
"command": "npx",
"args": ["-y", "mcp-sandman", "--config", "/path/to/sandman.toml"]
}
}
}之后 agent 只看得见上面那两个工具,不能写文件,只能访问你列出的主机。
作为库使用
import { serve, exposedTools, init } from 'mcp-sandman';
// 当作 MCP server 拉起来
const proxy = serve({ config: './sandman.toml' });
// 或者只问策略放行了什么,不真的启动
console.log(exposedTools('./sandman.toml')); // ['read_file', 'fetch_url']
// 或者生成一份起步策略
console.log(init('npx -y @acme/db'));策略
name = "db-sandbox"
# 顶层键必须写在任何 [表] 之前
audit_log = "./audit.log"
[upstream]
transport = "stdio"
command = "npx"
args = ["-y", "@acme/db-mcp"]
[tools]
allow = ["query_*", "describe_*"] # 留空 = 放行 server 提供的全部工具
deny = ["drop_*", "*_admin"]
require_non_empty = true # 策略把工具全挡掉时拒绝启动
[filesystem]
read = ["**"] # 相对于工作目录
write = [] # 默认只读
[network]
allow_hosts = ["*.internal.corp"]
allow_ports = [443]
[limits]
call_timeout_ms = 30000
max_response_bytes = 8388608
# 拒绝参数里看起来像凭据的调用
secret_patterns = ['sk-[A-Za-z0-9]{20,}']mcp-sandman check --config sandman.toml 校验策略但不连接任何东西。
mcp-sandman doctor 会真的连上去,列出放行的工具——找工具名拼错最快的方式。
HTTP 上游
默认是 stdio,也是 npm 包带的那份。要沙箱化一个远程服务器,开 feature 并改传输方式:
[upstream]
transport = "http"
url = "https://mcp.example.com/rpc"
[upstream.headers]
Authorization = "Bearer ${MCP_TOKEN}" # 从环境变量展开cargo build --release --features http沙箱会往这个端点 POST JSON-RPC,两种响应格式都能处理:普通 JSON body,或者 SSE 流。 两种模式下策略的行为完全一致。
两条值得记住的规则
除非策略里写了绝对路径,否则绝对路径一律拒绝。 read = ["**"] 只匹配相对路径。
这是故意设计的:glob 引擎里的 ** 会跨 / 匹配,不加这条规则的话 read = ["**"]
会悄悄放行 /etc/shadow。真要「全部放行」,就写 ["/**"]。
审计日志只记参数名,绝不记参数值。 一个把参数值存下来的审计日志,本身就是个泄密 的地方。
命令
命令 | 作用 |
| 在 stdio 上服务,默认行为 |
| 校验策略,不连接 |
| 连接并列出放行的工具 |
| 为一条命令生成起步策略 |
日志永远走 stderr。stdout 是 JSON-RPC 流。
它不是什么
mcp-sandman 检查的是 agent 发出的参数。如果 server 在运行时自己拼路径,或者读了 一个 agent 根本没提到的文件,参数检查拦不住它。真正不可信的 server,请配合容器隔离 模式:
[isolation]
isolation = "container"
image = "node:22-slim"
args = ["--network=none", "--read-only"]那一层无论 server 做什么都拦得住。mcp-sandman 的价值在于它不需要容器运行时,容易被 采纳。
安全细节
上游进程启动时环境变量是清空的。只给它
PATH、HOME、locale,加上[upstream.env]里明确列出的变量——而不是启动 agent 的那个进程的全部环境。拒绝是以
isError: true的工具返回值给出的,不是协议层错误。agent 能读到拒绝 原因并调整,会话不会中断。拒绝信息会说明为什么。「路径 X 不在策略范围内」会让 agent 换个路径再试; 「工具不可用」会让它满世界找别的工具。
开发
cargo test --all-features # 52 个 Rust 测试
npm test # 11 个包装器测试
cargo clippy --all-targets --all-features
cargo build --release
python fixtures/insecure_server.py # 一个故意不安全的 MCP server
mcp-sandman --config fixtures/insecure.toml doctorfixtures/insecure_server.py 提供了 read_file、write_file、fetch_url、
delete_everything,自身没有任何检查。它存在是为了让测试和这份文档描述的是真实、
可复现的结果,而不是一厢情愿的设想。
改 npm 包时:
cargo build --release
cp target/release/mcp-sandman.exe bin/mcp-sandman.exe # Windows 上是 .exe
node bin/mcp-sandman.js --help
node scripts/publish.js --dry-run在预编译二进制发布之前,npm install 没法验证下载路径;用 MCP_SANDMAN_BINARY
指向本地编译产物。
CI 里包含 cargo test --all-features 和 cargo clippy --all-features——http
feature 只在开启时编译,所以需要显式覆盖。
许可证
MIT
致谢
设计思路借鉴了这个领域已有的工作: pro-vi/mcp-filter 的中间代理形态和配置驱动 的工具规则, Automata-Labs/code-sandbox-mcp 的容器生命周期处理,以及 Model Context Protocol 协议规范本身。本仓库所有 代码均为原创。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Open-source MCP gateway with per-agent tool permissions, call approvals and tool-change review.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA least-privilege enforcement proxy for MCP servers. It sits between MCP clients and upstream servers, enforcing tool policies, hiding denied tools, requiring human approval for risky actions, and providing a structured audit trail.MIT
- AlicenseNot gradedqualityCmaintenanceAn authorizing reverse proxy for MCP servers that enforces per-call policy rules on tool arguments with audit logging, dry-run, and rate limiting.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProxies MCP traffic between a client and a downstream server to enforce runtime policies on tool declarations, call arguments, and results, including allowlisting, sandboxing, secret and egress controls, and injection detection. It also includes a deterministic benchmark for measuring which security controls stop which attacks.MIT
- AlicenseNot gradedqualityCmaintenanceA transparent MCP stdio proxy that sits between an agent client and a real MCP server, intercepting tools/call requests to enforce runtime guardrails derived from the same YAML rules used for CI regression testing. It blocks forbidden, out-of-whitelist, looping, or non-idempotent tool invocations with JSON-RPC errors and writes every decision to an audit log.1MIT