内容
# mcp-guard
[](https://golang.org/)
[](https://opensource.org/licenses/MIT)
> **本地隐私防火墙，秘密清理工具和 AI 编程代理的令牌压缩工具。**
Model Context Protocol（MCP）服务器的安全防护代理。
`mcp-guard` 是一个超快速、无依赖的 Go 二进制文件，它透明地位于您的编辑器（Claude Code、Cursor、VS Code）和任何 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器之间。
它作为一个本地安全代理，确保您的敏感 API 密钥、数据库凭证和受保护路径（`~/.ssh`、`.env`、`.git`）**永远不会泄露给云 LLMs** 或被自主工具执行。
---
## 为什么使用 mcp-guard？
当 AI 代理运行诸如 `@modelcontextprotocol/server-filesystem` 或 `postgres-mcp` 之类的工具时，它们直接从磁盘读取原始文件。如果文件中包含 AWS 密钥、JWT 或数据库密码，**这些凭证将以明文形式直接发送到云 AI API。**
`mcp-guard` 在您的机器上本地运行，以解决这个问题而不会破坏代理执行：
- 🔒 **零信任输入/输出检查：** 拦截 `stdin`/`stdout` 上的请求和响应。
- ⚡ **零依赖 Go 二进制文件：** 可忽略的性能开销（< 1ms 执行惩罚）。
- 🔄 **可恢复的防护错误：** 发送结构化的 `isError: true` 响应，以便 AI 代理可以优雅地自我纠正，而不是因传输失败而崩溃。
---
## 架构
```
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐
│ │ │ │ │ │
│ 编辑器 / MCP 客户端 │ stdin │ mcp-guard │ stdin │ MCP 服务器 │
│ ├─────────►│ ├─────────►│ │
│ （Claude Code / Cursor）│ │ • 拦截写入 │ │ （例如，文件系统， │
│ │ stdout │ • 清除秘密 │ stdout │ postgres，github） │
│ │◄─────────┤ • 压缩上下文 │◄─────────┤ │
└─────────────────────────┘ └─────────────────────────┘ └─────────────────────────┘
```
---
## 特性
### 1. 🔑 秘密和凭证清除（服务器 ➔ 客户端）
在工具结果能够到达 LLM 之前，扫描 10 多种敏感凭证格式：
* **云和 AI 密钥：** AWS（`AKIA...`）、Anthropic、OpenAI、Stripe、Google、GitHub PAT。
* **数据库 URI：** 掩盖 `postgres://user:pass@host`、`mongodb+srv://`、`redis://` 中的密码。
* **私钥和 JWT：** RSA/PEM 密钥和 Bearer 令牌的完整块掩盖。
```env
# 在 mcp-guard 之前：
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
DATABASE_URL=postgres://admin:SuperSecret123!@db.internal:5432/prod
# 在 mcp-guard 之后：
AWS_ACCESS_KEY_ID=[REDACTED:aws-access-key]
DATABASE_URL=postgres://admin:[REDACTED:uri-credentials]@db.internal:5432/prod
```
### 2. 🛡️ 防护策略和写入保护（客户端 ➔ 服务器）
防止 AI 代理修改或读取受保护路径，无论相对路径遍历技巧（`../.ssh`）如何：
* **受保护路径：** `~/.ssh`、`~/.aws`、`~/.gnupg`、`~/.kube`、`.git`、`.env*`
* **敏感文件：** `id_rsa`、`authorized_keys`、`.npmrc`、`.netrc`、`.pypirc`
* **Shell 脚本阻止：** 默认阻止危险的 shell 执行工具。
### 3. ⚡ 上下文令牌压缩（可选）
剥离冗余的行/块注释和空格，以节省上下文窗口容量。
> *注意：压缩会自动跳过用于编辑的工具（`read_file`、`get_file_contents`），以保留精确的差异边界，以便安全的文件编辑。*
---
## 安装
```bash
# 通过 Go 安装
go install github.com/sainitish1609/mcp-guard/cmd/mcp-guard@latest
# 或从源代码构建
git clone https://github.com/sainitish1609/mcp-guard.git
cd mcp-guard
go build -o mcp-guard ./cmd/mcp-guard
---
## 配置和集成
### Claude Code
使用 `mcp-guard --` 包装任何标准 MCP 服务器命令：
```bash
claude mcp add postgres -- mcp-guard --redact-secrets --max-tokens 4000 -- npx -y @modelcontextprotocol/server-postgres
```
### Cursor / VS Code (`.vscode/mcp.json`)
```json
{
"mcpServers": {
"filesystem": {
"command": "mcp-guard",
"args": [
"--redact-secrets",
"--block-shell",
"--",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/projects"
]
}
}
}
```
---
## 标志参考
| 标志 | 默认值 | 描述 |
| --- | --- | --- |
| `--redact-secrets` | `true` | 屏蔽工具响应中的 API 密钥、令牌和数据库密码 |
| `--block-shell` | `true` | 阻止执行 shell 脚本 |
| `--annotate-tools` | `true` | 将策略通知追加到 `tools/list`，以便代理事先了解边界 |
| `--compress` | `false` | 剥离上下文中的注释和空行（仅限安全工具） |
| `--max-tokens N` | `0` | 每个结果块的近似令牌预算上限（0 = 无限制） |
| `--protect-paths` | *(默认值)* | 自定义逗号分隔的受保护路径（覆盖默认值） |
| `--log-level` | `info` | 设置日志详细程度（`silent`、`error`、`info`、`debug` 输出到 **stderr**） |
| `--dry-run` | `false` | 将安全事件记录到 stderr 而不修改 stdin/stdout |
---
## 测试和验证
```bash
# 运行单元测试和集成测试
go test ./... -v
# 运行静态分析
go vet ./...
```
---
## 许可证
在 MIT 许可证下分发。有关详细信息，请参见 [`LICENSE`](https://www.google.com/search?q=LICENSE)。
