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,并可自动检测
Related MCP server: llm-cost-guard
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Agent Cost Allocator MCP — multi-tenant LLM cost attribution for chargeback billing. Companion to
MCP gateway: one connection for your AI apps, with tool policies, PII redaction and audit logs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for AI agent security guardrails. Provides input validation, prompt injection detection, PII redaction, output filtering, policy enforcement, rate limiting, and comprehensive audit logging.72 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for tracking LLM costs, setting spending limits, and receiving budget alerts directly within AI editors via slash commands like /guard.7 npm1MIT
- AlicenseBqualityAmaintenanceGovernance runtime for AI agents: a guard tool evaluates risky actions against policy before they execute (block / warn / require human approval), approvals route to a human queue, and every action becomes a replayable decision record with per-action spend tracking. Runs over stdio via npx @dashclaw/mcp-server; works with Claude Code, Codex, LangChain, CrewAI, or any MCP host.68320MIT
- AlicenseAqualityBmaintenanceMartinLoop is the independent governance and financial control layer for AI coding agents. Set hard spend limits, prevent runaway loops, enforce verification, trigger rollback on failure, and generate auditable receipts showing what changed, what it cost, and whether the work passed.24224 npm263Apache 2.0