agent-guard-mcp
agent-guard-mcp
MCP Guard Server — 为 AI Agent 提供预算控制、审批工作流和审计日志记录。
适用于 Claude Code、Cursor、ChatGPT 以及任何支持 MCP 协议的 AI Agent。
功能特性
预算控制 — 设置每日额度硬上限，防止 Agent 超支
高风险审批 — 超过金额阈值或匹配敏感资源关键字的操作将触发人工审批
审批工作流 — Agent 发起请求 → 生成令牌 → 人工通过仪表板或 Telegram 进行审批
审计日志 — 记录所有支出、审批和拒绝操作，支持基于游标的分页查询
Web 仪表板 — 基于 Gin + HTMX + Tailwind 的实时仪表板
Telegram 通知 — 为高风险操作提供即时审批链接
多传输协议 — 支持 stdio / SSE / StreamableHTTP，并可自动检测
MCP 工具
工具 | 描述 |
| 查询今日预算状态 |
| 执行支出（自动检测高风险） |
| 显式请求人工审批 |
| 批准待处理的令牌 |
| 拒绝待处理的令牌 |
| 轮询审批状态 |
| 带过滤和分页功能的审计日志查询 |
| 列出所有待处理的审批请求 |
快速开始
要求
Go 1.24+
无需 CGO（纯 Go SQLite 驱动）
从源码构建
git clone https://github.com/dygogogo/agent-guard-mcp.git
cd agent-guard-mcp
go build -o mcp-guard main.go下载预编译二进制文件
下载适用于您平台的最新版本：
平台 | amd64 | arm64 |
macOS | ||
Linux | ||
Windows |
或者访问 最新发布 页面。
配置
通过环境变量或 .env 文件进行配置：
变量 | 描述 | 默认值 |
| 传输协议: stdio / sse / http | 自动检测 (TTY → http) |
| 每日预算上限 (额度) | 10.0 |
| 高风险金额阈值 | 2.0 |
| 高风险资源关键字 (逗号分隔) | delete,send |
| SQLite 数据库路径 | ./mcp-guard.db |
| 仪表板 HTTP 端口 | 8080 |
| 审批链接的基础 URL | |
| 日志级别: debug/info/warn/error | info |
| 付款人标识 | hostname |
| Telegram 机器人令牌 (可选) | - |
| Telegram 聊天 ID (可选) | - |
运行
# HTTP mode (auto-detected, with Dashboard)
./mcp-guard
# Dashboard: http://localhost:8080/dashboard
# MCP endpoint: http://localhost:8080/mcp
# stdio mode (for MCP clients)
MCP_TRANSPORT=stdio ./mcp-guard
# SSE mode
MCP_TRANSPORT=sse ./mcp-guard
# SSE endpoint: http://localhost:8080/sseClaude Code 集成
添加到 Claude Code 的 MCP 配置中：
{
"mcpServers": {
"agent-guard-mcp": {
"command": "mcp-guard",
"env": {
"MCP_TRANSPORT": "stdio",
"BUDGET_LIMIT": "10"
}
}
}
}架构
┌─────────────┐ MCP Protocol ┌────────────────┐
│ AI Agent │ ◄──────────────────► │ MCP Guard │
│ (Claude, │ stdio / HTTP │ Server │
│ Cursor...) │ │ │
└─────────────┘ │ ┌────────────┐ │
│ │ BudgetStore │ │
┌─────────────┐ HTTP │ │ (SQLite) │ │
│ Dashboard │ ◄──────────────────► │ └────────────┘ │
│ (Gin+HTMX) │ └────────────────┘
└─────────────┘
┌─────────────┐ Webhook
│ Telegram │ ◄────── Approval notifications
└─────────────┘核心文件
文件 | 描述 |
| 入口点、传输选择、优雅关闭 |
| 包含 8 个已注册工具的 MCP 服务器 |
| BudgetStore 接口 + SQLite 实现 |
| 高风险检测、审批工作流、Telegram |
| 环境配置、自动传输检测 |
| zap 日志记录 (stdio 模式: 仅限文件) |
| Gin Web 仪表板 |
审批工作流
1. Agent calls spend(amount=5.0, resource="/api/delete")
2. MCP Guard detects high-risk (amount > threshold OR resource keyword matched)
3. Returns {status: "pending_approval", token: "xxx"}
4. Agent polls check_approval(token) for status
5. Human approves/rejects via Dashboard or Telegram
6. Agent receives final result (approved/rejected/budget_exceeded)测试
# All tests with race detection
go test -race -count=1 ./...
# Integration tests only
go test -race -run TestIntegration -v ./...
# Coverage
go test -race -cover ./...技术栈
Go 1.24 — 编程语言
mcp-go — MCP 协议 Go SDK
Gin — Web 框架 (仪表板)
modernc.org/sqlite — 纯 Go SQLite (无 CGO)
zap — 结构化日志记录
HTMX + Tailwind CSS — 仪表板前端
许可证
MIT
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dygogogo/agent-guard-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server