mcp-warden

mcp-warden

面向 Model Context Protocol 的本地优先凭据代理——让任何 AI 编码 Agent（Claude Code、Cursor、Cline、Codex、Continue、Zed）都能执行实际操作，同时始终看不到你的密钥。

Agent 调用高级工具（proxy_http）；mcp-warden 在服务端注入密钥、执行操作，并且只返回结果。你的上下文窗口始终干净。即使对话记录泄露，也不会泄露任何有用信息。

工作原理

1. 通过 mcp-warden CLI 将凭据存入 OS 钥匙串一遍即可。
2. 定义预设——命名且限定范围的操作（例如 github-read、stripe-charges）。
3. AI Agent 通过 stdio 将 mcp-warden 作为 MCP 服务连接。
4. Agent 需要执行操作时，会使用预设名称和路径／方法调用 proxy_http。
5. mcp-warden 根据预设的允许列表验证请求，注入凭据、执行操作，并且只返回响应。
6. 敏感预设会触发审批提示：macOS 和 Windows 上显示原生对话框，Linux 上显示带有批准／拒绝选项的桌面通知；也可在任何 OS 上通过 Telegram 审批——其中 /lock 还能在手机上用作紧急停止开关。你可以选择为每个预设启用限时审批，这样一次批准即可涵盖短时间内的一连串后续调用，避免反复提示。
7. 每项操作都会写入本地 SQLite 审计日志——包括由有效审批时段授权的调用所对应的 windowed 决策、允许列表拒绝的调用所对应的 refused 决策（其中包含原始请求路径或命令），以及无法显示审批提示时所对应的 failed 决策。

Agent 的上下文窗口中不会包含任何密钥。

安装

cargo install --locked mcp-warden # from crates.io
cargo install --locked --path .   # or from a clone

每个 GitHub release 都附带适用于 macOS（x86_64、aarch64）和 Linux（x86_64）的预编译二进制文件，以及各自的 SHA-256 校验和。

90 秒快速入门

mcp-warden init
mcp-warden secret add gh_pat                  # paste your GitHub PAT when prompted
mcp-warden preset add github-read \
  --type http \
  --base-url https://api.github.com \
  --auth-bearer gh_pat \
  --allowed-methods GET \
  --allowed-paths /user/repos \
  --approval auto --confirm-auto

该预设仅自动批准 GET /user/repos；其他任何路径都会在令牌被访问前遭到拒绝。如需让 Agent 读取更多内容，请扩大允许列表（例如 --allowed-paths '/user/repos,/repos/OWNER/[^/]+'），并优先使用仅限特定仓库的细粒度 PAT。模式会匹配整个路径，可以是精确字符串，也可以是以 ^(?:…)$ 锚定的正则表达式；绝不会按前缀匹配。对于单个路径段，[^/]+ 比 .* 更安全。路径会先进行百分号解码，因此 %2F 会被视为分隔符：类似 GitLab 的 /projects/group%2Fproject ID 需要使用 /projects/[^/]+/[^/]+。没有 allowed_paths 的 HTTP 预设会允许 base_url 下的所有路径——preset add 和 doctor 会对此发出警告，内置的 github-read / gitea-read / stripe-read 模板则因此默认设置 approval = "prompt"。

将 mcp-warden 接入你的 Agent——请参阅 docs/claude-code-setup.md 或 docs/cursor-setup.md。

在 Agent 中询问：“通过 mcp-warden 列出我的 GitHub 仓库。”观察 Agent 调用 list_presets，然后调用 proxy_http——同时确认你的 PAT 不会出现在提示词中。

mcp-warden audit --last 5                     # see what the agent did

查找并修复明文密钥

粘贴到 MCP 客户端配置中的密钥会以明文形式存储在磁盘上，Agent、同步的 dotfile 或截图都可能将其泄露。三个命令即可解决：

mcp-warden scan                     # where are plaintext keys? (shows type + length, never values)
mcp-warden import                   # move them into the keychain and rewire the client entries
mcp-warden run github               # what the rewired entry runs: the server, with its key injected

scan 会读取 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code 和 Codex 配置，以及当前目录中的 .mcp.json / .env 文件（使用 --path DIR 可扫描更多文件）。import 会处理 stdio 服务的 env 中的密钥；对于参数、标头、URL 或 .env 文件中的密钥，scan 会说明该如何处理。手动包装服务：mcp-warden server add github --env GITHUB_PERSONAL_ACCESS_TOKEN -- npx -y @modelcontextprotocol/server-github（密钥值从 stdin 读取）。详情请参阅：docs/scan-and-import.md。

CLI 参考

命令	说明
mcp-warden init	创建配置目录和模板配置
mcp-warden secret add <name>	存储密钥（密钥值从 stdin 读取，不会通过 argv 传递）
mcp-warden secret list	列出密钥名称（绝不显示密钥值）
mcp-warden secret remove <name>	从钥匙串中删除密钥
mcp-warden preset add <name> ...	定义预设（使用 auto 时必须指定 --confirm-auto）
mcp-warden preset list	显示所有预设
mcp-warden preset test <name>	根据当前钥匙串验证预设
mcp-warden preset test <name> GET /path	策略模拟器：此调用会被允许吗？原因是什么？不会发送任何内容（其他工具可使用 --command、--get/--put、--query）
mcp-warden preset grant <name> --for 1h	授予限时访问权限：超过时限后将拒绝调用（使用 --permanent 可清除时限）
mcp-warden preset revoke <name>	立即结束对预设的访问权限（在下次服务启动时生效；使用 lock 可立即生效）
mcp-warden lock [--reason …]	紧急开关：从下一次启动起，所有 MCP 服务都会拒绝所有调用（或向 Telegram 机器人发送 /lock）
mcp-warden approval telegram-test	检查 Telegram 配置：令牌、聊天，以及一个需要你回答的测试提示词
mcp-warden unlock	经人工在对话框 / Telegram 中批准后解除锁定
mcp-warden scan	查找 MCP 客户端配置和 .env 文件中的明文密钥（绝不打印密钥值）
mcp-warden import	将 scan 找到的密钥移入钥匙串，并将客户端指向 mcp-warden run
mcp-warden server add <name> --env VAR -- <cmd…>	包装另一个 MCP 服务；其密钥从 stdin 读取并存入钥匙串
mcp-warden run <name>	启动已包装的 MCP 服务并注入其密钥（用作客户端的命令）
mcp-warden preset scaffold <template> (v0.3.0)	根据内置模板生成预设（使用 --list 查看可用模板）
mcp-warden preset from-openapi <src> (v0.3.0)	根据 OpenAPI 3.x 规范（URL 或文件）快速创建预设
mcp-warden approval <preset> <policy> [--window N]	设置审批策略；--window N（秒）可为 prompt 启用限时审批
mcp-warden audit [--last N | --since T]	只读查看审计日志（按设计仅追加），包括 Agent 请求的内容（含被拒绝的调用），以及发起每次调用的 MCP 客户端和会话
mcp-warden doctor [--deep] (v0.3.0 for --deep)	诊断摘要；--deep 会针对每个预设执行安全的只读 HTTP 探测
mcp-warden web [--port N] (v0.3.0)	本地只读 Web 界面（仅绑定到 127.0.0.1）
mcp-warden mcp	通过 stdio 运行 MCP 服务（供 AI Agent 使用）

暴露的 MCP 工具

• list_presets — 只读的可用操作目录。
• proxy_http — 通过预设执行 HTTP 请求；在注入凭据前会进行允许列表验证。
• ssh_exec （v0.2.0） — 在 SSH 主机上运行 shell 命令；命令必须匹配预设中锚定的正则表达式允许列表；使用基于密钥的身份验证和主机密钥验证。
• sftp_transfer （v0.2.0） — 通过 SFTP 获取或上传文件；远程路径须匹配预设的 sftp_allowed_paths，本地路径须位于 $HOME 或 /tmp 下。
• db_query （v0.2.0） — 对 PostgreSQL / MySQL / Redis 运行命名查询。SQL/命令在预设定义中固定；Agent 只提供 query_name 和位置参数。
• get_secret_for_env — 子进程必须从 env 读取密钥时的最后手段。无论预设策略如何，都会始终请求批准。

Claude Code 插件

对于 Claude Code，有一个插件，其中包含 MCP 服务配置、一个教 Claude 正确使用 mcp-warden 的技能（先发现预设、绝不索要令牌、遵守审批要求，并将 get_secret_for_env 视为最后手段），以及引导式 /mcp-warden:setup 命令。请先安装二进制文件，然后在 Claude Code 中：

/plugin marketplace add ermoluk/mcp-warden
/plugin install mcp-warden@mcp-warden

重启 Claude Code 并运行 /mcp-warden:setup。如果你之前通过 claude mcp add 添加了该服务，请移除该条目，以免重复注册。详情：plugins/mcp-warden/。

其他 MCP 客户端：请参阅 docs/claude-code-setup.md 和 docs/cursor-setup.md 了解手动设置方法。

v0.5.1 新增内容

• cargo install mcp-warden 可以再次正常构建。 由于 keyring crate 的一个次要版本移除了它所用的函数，0.5.0 在不使用 --locked 的情况下无法编译。mcp-warden 现在直接与操作系统密钥链存储交互，早期版本保存的密钥仍可读取。请使用 cargo install --locked mcp-warden 安装。

v0.5.0 版本新增内容

• 所有桌面系统都支持审批。 prompt 预设现在会在 macOS 和 Windows 上通过原生对话框询问：默认拒绝，按 Return / Esc 拒绝，并在 60 s 后自动拒绝。在 0.4.x 中，除非配置了 Telegram，否则 MCP 客户端无法批准 macOS 上的 prompt 预设。无法显示的提示会被拒绝，并以 failed 记录审计日志。
• 紧急停止开关。 mcp-warden lock 会让所有正在运行的 MCP 服务从下一次调用开始拒绝所有调用。已收到锁定指令的服务会一直保持锁定状态，直到重启。mcp-warden unlock 需要你在对话框或 Telegram 中批准。配置 Telegram 后，也可以通过手机发送 /lock 执行同样的操作。
• 查找并修复明文密钥。 mcp-warden scan 会查找粘贴到 MCP 客户端配置和 .env 文件中的 API 密钥；它绝不会打印密钥值。mcp-warden import 会将密钥移入密钥链，而 mcp-warden run <name> 会在注入密钥后启动服务（参见查找并修复明文密钥）。
• 限时访问和策略模拟器。 preset grant <name> --for 1h 和 preset revoke <name> 可限制预设的生效时长。preset test <name> GET /path 会告诉你某个调用是否会被允许，以及原因，而不会发送任何内容。
• 更严格的响应处理。 上游回显的凭据会在 Agent 看到之前被清除。对于每个预设，max_response_bytes 可限制响应正文大小，response_fields 则只返回你列出的字段。
• 更完善的审计记录。 每个事件都会注明发起操作的 MCP 客户端和会话。
• Telegram 支持多个会话。 多个 Claude 会话可以共用一个机器人：它们轮流轮询机器人，因此按钮点击不再丢失。mcp-warden approval telegram-test 会端到端检查配置。
• 新增五个模板： gitlab-read、linear、jira-read、slack-read、vercel-read。
• 行为变更：
  • MCP 服务会在启动时读取一次 config.toml，因此编辑预设后需要重启服务；
  • 最低 Rust 版本现为 1.89。

完整列表：CHANGELOG.md。

v0.4.0 版本新增内容

• 工作区拆分。 项目现在分为两个 crate：mcp-warden-core（库 — trait 接口 + 共享类型）和 mcp-warden（二进制程序 — CLI、MCP 服务、执行器、Web UI、具体的审批传输方式）。KeychainStore、ApprovalTransport、AuditSink 或 PresetSource 的替代实现现在只需依赖 mcp-warden-core，无需引入二进制程序的 GUI / 运行时依赖。
• 接入 Telegram 审批传输方式。 该实现已在 v0.3.0 中存在；v0.4.0 让它真正变为可选配置。在配置文件中添加以下内容（mcp-warden doctor 会打印配置文件路径：Linux 上为 ~/.config/mcp-warden/，macOS 上为 ~/Library/Application Support/io.mcp-warden.mcp-warden/）：

  [approval.telegram]
  bot_token_secret = "tg_bot_token"   # name of the keychain entry, not the token value
  chat_id = 123456789                  # your numeric Telegram chat id
  timeout_seconds = 120                # optional
  

  然后运行 mcp-warden secret add tg_bot_token（将机器人令牌粘贴到密钥链中）。prompt 策略预设现在会向该聊天发送带有 Approve / Deny 内联按钮的消息；如果 Telegram 提示超时，macOS 会再次通过原生对话框询问（参见 docs/approval-transports.md）。可在运行时通过 MCP_WARDEN_APPROVAL_TRANSPORT={telegram|desktop|tui} 覆盖。

v0.3.0 中的新功能

• preset scaffold — 为最常见的 API 内置了 8 个模板（github-read、github-write、notion-read、stripe-read、openai-chat、anthropic-messages、gitea-read、cloudflare-dns）。只需一条命令即可生成可用的预设，无需从指南中复制粘贴。
• preset from-openapi <url-or-file> — 指定一个 OpenAPI 3.0/3.1 JSON 或 YAML 规范，它会据此生成 base_url、allowed_paths、allowed_methods 和身份验证方案（Bearer 或 APIKey-Header）。可按 HTTP 方法或标签筛选。
• doctor --deep — 针对每个 HTTP 预设运行安全的只读探测（对基础 URL 或首个字面允许路径发送 GET 请求），报告 ok / auth_failed / auth_ok_404 / network_error / tls_error / skipped，以及耗时和已脱敏的响应正文片段。除非传入 --include-prompt，否则跳过 prompt 策略的预设。
• web — 一个仅在本地运行的小型 Web UI（绑定到硬编码地址 127.0.0.1），可用于浏览预设和审计日志，无需启动 TUI。此版本中为只读；通过 WebSocket 审批功能已列入路线图。
• Telegram 审批传输 — 新增 ApprovalTransport 实现，可将审批提示发送到 Telegram 聊天，并附带内联的 Approve / Deny / Approve-for-window 按钮。机器人令牌保存在 OS 钥匙串中。会拒绝来自非授权聊天的回调。消息使用 protect_content: true。配置 [approval.telegram] 后会自动选用。

有关 Web UI 的设计说明，请参阅 docs/web-ui.md。

安全模型

mcp-warden 的威胁模型和安全不变量见 docs/threat-model.md。概括来说：

• 密钥仅保存在 OS 钥匙串中——绝不以明文形式写入磁盘，也绝不写入日志。
• 如果上游在 proxy_http 响应中回显凭据（例如回显端点，或引用令牌的错误），在 Agent 看到响应前，这些凭据会被替换为 [redacted by mcp-warden]。响应的其余部分属于不可信的上游数据，会原样传递。
• 允许列表验证在注入凭据之前执行。
• 默认审批策略为 prompt；创建预设时，auto 需要 --confirm-auto。
• MCP 服务在启动时加载并验证一次 config.toml，之后不会重新读取：编辑预设后需重启服务。
• 审计日志仅追加——trait 接口本身不包含 delete / clear 方法。
• mcp-warden lock 会在每个正在运行的服务下一次调用时将其停止；已收到锁定信号的服务会一直保持锁定状态，直到重启，而 unlock 需要人工批准。
• 预设可以限制并裁剪 proxy_http 交给 Agent 的内容（max_response_bytes、response_fields）；上游回显的凭据始终会被清除。
• 被包装的服务（mcp-warden run）只能获取为其保存的密钥（server/<name>/<VAR>），无法获取预设的密钥，其命令也固定在配置中。传递给进程的密钥仍对该进程可见。
• Stdout 是 MCP 协议通道；所有日志都输出到 stderr。

链接

• crates.io：mcp-warden
• MCP Registry 名称：mcp-name: io.github.ermoluk/mcp-warden

许可证

Apache-2.0 — 对 OSS 核心的永久承诺。请参阅 LICENSE。

mcp-warden 将永远保持功能完整且免费——请参阅我们的开源核心承诺。