Cisco Duo MCP

Cisco Duo + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Claude Code Skill 和 Cisco Duo API 的 MCP 服务。与 Cisco Systems, Inc. 无关，也未获得其认可或赞助。

_{完整 Skill 页面 - 安装、使用效果、安全模型。}

用一条命令修复 Duo MFA 锁定，并一次查看所有 MSP 子账户，同时使用签名的 Admin API 调用。可与您现有的 AI 搭配使用 - ChatGPT（Plus/Pro+，在此连接器重新发布前暂停使用；请参阅 mcp-install.md）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot - 也可通过远程方式使用 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini。免费、开源，可在您的笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于您的 Agent

安全提示（在此连接器重新发布之前）。 请勿运行 HTTP 模式 （--transport http），即使是在 localhost 上也不行。此版本会检查令牌，但 早于修复版，因此尚未实现请求大小和时间限制。MCP 工具 也可以使用您的凭据进行更改。请使用默认的 stdio 传输方式。如果 您为远程 Agent 设置了隧道，请将其关闭。修复即将推出。

MSP 所有者实际使用的六种 Agent（ChatGPT 在此连接器重新发布前暂停使用，详见下文）：

您的 AI Agent	如何安装 Cisco Duo Skill
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 cisco-duo-mcp（无需编辑 JSON）。
ChatGPT（付费套餐）	在此连接器重新发布前暂停使用：ChatGPT 需要 HTTP 模式，而此版本的该模式会检查令牌，但尚未实现请求大小和时间限制。请参阅 mcp-install.md 中的安全提示。
Codex CLI	粘贴下方的安装提示词。
Claude Code	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，在 mcp.json 的 servers 键下添加 cisco-duo-mcp，然后选择 Agent 模式。

ChatGPT 需要远程 HTTPS 服务，也就是说需要使用此连接器的 HTTP 模式；在连接器重新发布前，该模式将暂停使用：此版本的该模式会检查令牌，但尚未实现请求大小和时间限制。请参阅 mcp-install.md 中的安全提示。

Microsoft 和 Google 技术栈的使用方式

用户基数庞大，但需要坦诚说明：这些是远程 / 企业使用方式，不是你刚安装的本地二进制文件。

Agent	所需内容
Microsoft 365 Copilot / Copilot Studio	暂停支持，直到重新发布此连接器：Copilot Studio 需要 HTTP 模式，而此版本的该模式会检查令牌，但尚未限制请求大小或时长。请参阅 mcp-install.md 中的安全说明。
Google Gemini	Gemini CLI 是本地运行的——与 Claude Code 相同。Gemini app 是远程服务，需要使用与 ChatGPT 相同的暂停支持的 HTTP 模式。请参阅 mcp-install.md。

原生支持 Skill 的 Agent（也已涵盖）： Hermes 和 OpenClaw 会直接读取此 Skill 的 SKILL.md，也支持 MCP——请参阅下方的安装章节。此外，也可通过 MCP 与 Cursor、Windsurf、Cline、Continue.dev 和 Zed 配合使用。各工具的完整接入说明：docs/which-agent.md。

要运行多个 Agent？ 使用一条命令即可为所有 51 个以上受支持的 Agent 安装：npx skills add Servosity/msp-skills@latest（需要 Node.js，然后运行每个 Skill 的安装程序来安装 CLI / MCP 二进制文件）。请参阅 docs/which-agent.md。

60 秒完成安装

Claude Desktop 最快安装方式——一键安装 .mcpb

下载 Cisco Duo MCP (.mcpb)——然后打开 Claude Desktop > Settings > Extensions 并选择该文件。一键完成，无需 JSON 或 Shell。（在发布页面查看所有 Cisco Duo 版本。）

更喜欢使用 Claude Code 插件？添加一次市场，然后安装即可立即使用，无需列出目录：

/plugin marketplace add Servosity/msp-skills
/plugin install cisco-duo@msp-skills

方式 A——向 AI Agent 粘贴一条提示词（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork 中：

在此 Agent 工作区中安装来自 Servosity/msp-skills 的 Cisco Duo Skill 和 MCP 服务。如果此工作区使用 POSIX Shell（macOS、Linux、WSL 或 Bash），请运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.sh)。如果使用 Windows PowerShell，请运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.ps1 | iex。然后按照 README 进行身份验证，并运行 cisco-duo-cli --help 进行探索。

同一条提示词适用于任何能够运行 Shell 的 Agent。

方式 B——自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.sh)

安装程序会将 cisco-duo-cli（CLI）和 cisco-duo-mcp（MCP 服务）放入用户的 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现 Skill。

验证：

cisco-duo-cli --version

升级到最新版本

安装程序始终会获取当前版本——重新运行即可升级：

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.sh)

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/cisco-duo/install.ps1 | iex

Claude Desktop .mcpb 用户：下载最新的 .mcpb（见本节顶部），然后在 Settings > Extensions 中重新选择该文件。Claude Code 插件用户：/plugin update cisco-duo@msp-skills。

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请参阅 mcp-install.md 和 docs/which-agent.md，查看各 Agent 的接入说明——每个 Agent 都有单独章节，其中包括 GitHub Copilot 的 servers 键，以及远程 Microsoft 365 Copilot / Copilot Studio 使用方式。Claude Desktop 的 Settings > Extensions 面板是最简单的方式；mcp-install.md 中提供了 MCP 配置块（供偏好编辑 JSON 的用户使用）。

为 Hermes 安装

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/cisco-duo --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/cisco-duo --force

Hermes 原生支持 MCP，因此也可以直接使用 cisco-duo-mcp 服务——安装方式和环境变量相同。

为 OpenClaw 安装

告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/servosity/msp-skills/tree/main/skills/cisco-duo 安装 cisco-duo 技能。该技能说明了如何通过 openclaw: frontmatter 块安装其所需的 CLI（cisco-duo-cli）。

OpenClaw 尚未普遍开放；frontmatter 配置已预先提供，会在 OpenClaw 启动时立即生效。

身份验证

在 Duo Admin Panel 中，前往 Applications > Protect an Application > Admin API 并创建一个 Admin API 应用。MSP 在父级账户中创建该应用，并授予子账户权限。复制该应用的三个值：

export CISCO_DUO_API_HOST="api-XXXXXXXX.duosecurity.com"   # API hostname
export CISCO_DUO_IKEY="<integration key>"
export CISCO_DUO_SKEY="<secret key>"
cisco-duo-cli doctor

doctor 会检查 API 主机，然后发送一个经过签名的读取请求（GET /admin/v1/users?limit=1），并将凭证状态报告为 valid、rejected（HTTP 401）或 scope-limited（HTTP 403：应用缺少 Grant resource - Read 权限）。默认情况下，它以状态码 0 退出；脚本应添加 --fail-on error（密钥被拒绝时失败）或 --fail-on warn（权限范围受限时也失败）。密钥仅用于签署请求；不会发送给 Duo。

只授予工作流所需的权限：只读操作需要 Grant resource - Read、Grant read log 和 Grant read information；作为 MSP，--account-id 和 fleet 命令还需要 Grant accounts - Read，而 fleet summary 的用户数上限列需要 Grant user limits - Read。解锁用户、发放绕过码和更换手机还需要 Grant resource - Write。请参阅 governance.md。

使用单个客户或所有客户

作为 MSP，可在任何命令中添加 --account-id（子账户 ID，或 accounts list 中显示的准确名称），或设置 CISCO_DUO_ACCOUNT_ID。CLI 会在你的父级账户中查找该客户，向该客户自己的 API 主机发送请求，并为每位客户维护独立的本地存储。该存储的键名与你传入的内容完全一致，因此每位客户请选择一种格式并始终使用（账户 ID 最稳妥）：使用名称运行同步、再使用 ID 运行审计，会读取不同的存储。fleet summary、fleet risk 和 fleet find-user 始终涵盖所有客户。

审计前先同步

audit bypass、audit stale 和 search 会读取本地镜像。请为每个租户填充一次：

cisco-duo-cli sync --resources users,admins,phones,bypass_codes --account-id DA9VZOC5X63I2W72NRP9

sync 只从 Duo 读取数据，并将数据写入你用户账户下的 SQLite 文件。如果所需资源从未同步，或上次同步中途停止，审计会报告 complete=false，因此不会把空结果误认为租户状态正常。锁定、换手机、fleet 和失败相关命令始终读取实时数据。

此技能的作用

MSP 经常提出的问题	命令
为什么这个用户无法通过 Duo 验证？该怎么解决？	cisco-duo-cli lockout triage "[email protected]" --account-id "Acme Corp"
解锁该用户，并提供一个一小时有效、仅可使用一次的绕过码（先预览）	cisco-duo-cli lockout fix "[email protected]" --account-id "Acme Corp" --bypass
用户换了新电话号码。将其 Duo 账户迁移到新号码。	cisco-duo-cli phone-swap "[email protected]" --number +15551234567 --remove-old
这个人属于哪个客户？	cisco-duo-cli fleet find-user "[email protected]"
哪些客户有用户处于绕过状态、被锁定或从未注册？	cisco-duo-cli fleet risk
哪些客户的 Duo 用户数接近上限，或电话服务额度不足？	cisco-duo-cli fleet summary
这个租户中，谁可以跳过 MFA？是谁发放了他们的绕过码？	cisco-duo-cli audit bypass --older-than 30d
一周后仍未注册的用户有哪些？重新发送他们的注册邮件。	cisco-duo-cli enrollment chase --older-than 7d --limit 25
本周发生了哪些登录失败或被标记为欺诈的登录？涉及哪些用户？	cisco-duo-cli failures --since 7d
身份验证和连接是否正常？	cisco-duo-cli doctor

lockout fix、phone-swap 和 enrollment chase 会打印计划；只有添加 --apply 后才会执行更改。

完整命令参考：guide.md。有关 AI Agent 的操作约定（--agent、--dry-run，以及何时应在执行更改前确认），请参阅 AGENTS.md。

与众不同之处

Duo 的官方客户端库（duo_client_python、duo_api_golang）负责为请求签名，工作流则由你自行处理；而简单的 MCP 封装会将一个工具映射到一个端点。这些方式处理单条记录没有问题。但对于 MSP 实际会问的两个问题，它们就力有不逮：“为什么这个用户无法登录”（答案涉及用户、所属组、电话、绕过码和近期失败记录），以及 “在我们的所有客户中，哪些人……”（每个客户都是一个拥有独立 API 主机的子账户）。

此技能会自行为每个 Duo v5 请求签名，按名称将命令路由到相应客户，并提供组合查询结果。lockout triage 会读取用户、所属组、电话、绕过码和近期失败记录，并返回适用的解决方案；其中也会指出可能导致解锁无效的 Disabled 组。fleet risk 和 fleet summary 会通过一次调用查询所有子账户，并将无法读取的客户列在 fetch_failures 下，而不会将其计为零。audit bypass 和 audit stale 会从本地 SQLite 镜像读取数据，因此，查询整个租户中“谁可以跳过 MFA”只需执行一次本地查询。

此工具解决的痛点

• 锁定账户工单从来不只需查一项信息。用户状态、覆盖该状态的组、用户的手机、已发放的绕过码，以及过去一天的登录失败记录，分别位于 Admin Panel 的不同页面。cisco-duo-cli lockout triage 会返回所有这些信息，以及接下来要运行的命令。
• 修复需要按步骤进行：解锁、发放短期绕过码，或重新激活手机，同时不清除之前发放的代码。cisco-duo-cli lockout fix 会先制定方案，使用 --apply 则会执行方案并生成变更前后的记录。
• 手机丢失或换新，意味着要创建、关联、激活新手机，之后再停用旧手机。cisco-duo-cli phone-swap 分两次运行即可完成，而且绝不会删除其他用户共用的手机。
• 每个客户都是单独的 Duo 子账户，因此要查明“来电用户属于哪个客户”，就得逐个账户搜索（Duo Community 上的 MSP也在询问这种按客户划分账户的情况）。cisco-duo-cli fleet find-user 可以一次搜索所有账户。
• 绕过码在紧急情况结束后仍然有效。cisco-duo-cli audit bypass 会列出租户中所有仍有效的代码及其发放管理员，cisco-duo-cli fleet risk 则会按客户统计这些代码。

更长的说明请参阅 pain-point.md。

常见问题

这可以与 ChatGPT 搭配使用吗？

此版本暂不支持。ChatGPT（Plus、Pro、Team、Business、Enterprise 和 Education 计划；Free 版目前尚未开放 Developer Mode）只能通过 HTTPS 连接 远程 MCP 服务，因此需要以 HTTP 模式运行 Cisco Duo MCP 服务。此版本的 HTTP 模式会检查令牌，但尚未设置请求大小或时间限制，因此在重新发布连接器之前，请勿运行它或将其置于隧道后方。mcp-install.md 中的安全说明解释了原因。在此之前，请使用 Claude Desktop、Claude Code 或 Codex。

这可以与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 搭配使用吗？

可以——它们都支持 MCP。跨工具安装命令请参见上面的对照表，以及 docs/which-agent.md 中的详细说明。

我需要懂编程吗？

不需要。推荐的安装方式是在 Claude Code 或 Codex 中粘贴一句话——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是使用各操作系统对应的一行安装命令（bash 或 PowerShell）。两种方式都不需要编写代码。你只需输入一次 Cisco Duo 凭据。

我的 Cisco Duo 数据安全吗？

你的数据会留在你的电脑上。CLI 和 MCP 服务都是本地二进制程序。SQLite 镜像存放在你用户账户下的目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始批量数据。凭据从你的环境或 Agent 配置中读取；MSP Skills 绝不会将凭据打包进此代码库或传输到任何地方。

我需要 Duo MSP（父级）账户吗？

不需要。只要在单个 Duo 账户中配置 Admin API 应用，除了 fleet 命令以外，所有命令都可以对该账户运行。作为 MSP，请在父级账户中创建具有子账户权限（至少拥有 Grant accounts - Read 权限）的 Admin API 应用，然后使用 --account-id（或 CISCO_DUO_ACCOUNT_ID）即可对单个客户运行任意命令；fleet summary、fleet risk 和 fleet find-user 则可一次覆盖所有客户。

它需要哪些 Duo Admin API 权限？

仅授予工作流实际使用的权限；权限集是你最有力的控制手段。只读工作（分类处理、审计、故障排查）需要 Grant resource - Read、Grant read log 和 Grant read information。作为 MSP，--account-id 和机群命令还需要 Grant accounts - Read，因为 CLI 会在你上级账户的子账户列表中查找每位客户；机群摘要中的用户限额列需要 Grant user limits - Read。解锁用户、签发绕过码、更换手机和重新发送注册邮件需要 Grant resource - Write。管理员命令需要 Grant administrators - Read 或 - Write，账单管理中的 set-user-limit 需要 Grant user limits - Write。

让 AI 签发绕过码安全吗？

只有在有人参与审核的情况下才安全，这些命令也是为此设计的。lockout fix、phone-swap 和 enrollment chase 会先打印计划，只有添加 --apply 后才会执行更改。lockout fix 签发的绕过码只能使用一次，默认一小时后过期，并保留任何现有代码。请先通过工单以外的渠道验证来电者身份（users send-verification-push 会向他们发送 Duo Push）。设置 CISCO_DUO_MCP_READ_ONLY=1 后，MCP 服务会隐藏 lockout fix、phone-swap 和 enrollment chase，并且其 API 工具会拒绝所有非 GET 调用。

这会触发 Duo API 速率限制吗？

很少。客户端会根据 Duo 的速率限制响应控制请求频率，并在 Duo 返回 429 时退避重试。机群命令会对每个客户子账户发起少量请求；机群风险检查还会分页扫描用户和绕过码，通过 --max-scan-pages 限制扫描量，并标记达到扫描上限的客户。Duo 建议每分钟最多轮询一次身份验证日志，因此不要以更快的频率循环查询故障。

这会取代 Duo Admin Panel 吗？

不会，它是对 Duo Admin Panel 的补充。策略、应用和目录同步仍在 Admin Panel 中进行。此工具可通过你的 AI 回答帮助台和 MSP 常见问题，而这些问题在面板中需要逐步点击处理——例如锁定诊断、手机更换、跨客户风险和容量管理。

费用是多少？

免费，采用 Apache-2.0 许可。你只需为所使用的 AI Agent（Claude、ChatGPT、Codex 等）付费，费用由你的 AI 提供商收取，而非我们。

安全模型

层级	示例	建议的 Agent 策略
读取	lockout triage、fleet summary、fleet risk、fleet find-user、audit bypass、audit stale、failures、sync、search、export、所有 list 和 get、accounts list，以及不带 --apply 的 lockout fix、phone-swap 和 enrollment chase（它们只会输出计划）	允许
写入（常规）	users send-verification-push、phones send-sms-installation、groups create、tokens resync、identity-verification start、identity-verification cancel	使用 --dry-run（或命令自带的预览功能）预览，然后执行经审核的写入
MFA 访问／凭据	lockout fix --apply（解锁、绕过码、重新激活）、phone-swap --apply、users create-bypass-codes、phones create-activation-url、phones send-sms-activation、phones send-sms-passcodes、phones set-quarantine-status（解除隔离后，设备可再次进行身份验证）、users add-phone、users add-token、phones create、phones update（新号码会接收短信和电话验证因素）、users bulk-create（可创建状态为绕过的用户）、groups delete（删除 Disabled 组会解除对其所有成员的限制）、directory-sync sync-user（重新同步目录用户可能会重新启用该用户、为其关联手机并发送注册信息）、import --input file.jsonl（导入可以设置创建操作可设置的任何字段，包括状态绕过）、users enroll（向任意地址发送一次性注册码，并将该码返回给调用方）、enrollment chase --apply（向尚未注册用户存档中的地址发送注册链接；跳过 Disabled 组中的用户）、users create 和 users update（两者都可将用户状态设为绕过）、users add-group、users remove-group 和 groups update（Bypass 或 Disabled 组会覆盖用户自身的状态）、registered-devices block-device 和 unblock-device	仅限有人参与的操作；须先通过独立渠道验证调用方
破坏性操作	users delete、users bulk-trash、users remove-phone、users remove-token、phones delete、tokens delete、bypass-codes delete、webauthn delete、desktop-authenticators delete、phone-swap --delete-old	仅限有人参与的操作，且须明确确认
管理员／账单	admins create、admins update、admins delete、admins reset、admins clear-inactivity、accounts create、accounts delete（移除整个客户子账户）、billing set-edition、billing set-user-limit、billing set-telephony-credits	仅限操作员使用，不供 Agent 使用
批量写入	users bulk-restore（Duo 会将用户恢复为已禁用状态）	仅限有人参与的操作，且须明确确认。绝不可无人值守执行

MFA 访问层级最为重要：声称“我被锁定在账号之外”的调用方可能就是 MFA 要防范的攻击者。Agent 发出绕过码、激活链接或新手机之前，须通过独立渠道验证其身份（cisco-duo-cli users send-verification-push 会向其已有设备发送 Duo Push），并由人工批准操作计划。对于仅执行诊断的 Agent，请设置 CISCO_DUO_MCP_READ_ONLY=1：MCP 服务会隐藏 lockout fix、phone-swap 和 enrollment chase，其 API 工具也会拒绝所有非 GET 调用。

最有力的控制措施是 Admin API 应用的权限集——没有 Grant resource - Write 权限的应用无法解锁用户、发放代码或操作手机；没有 Grant administrators - Write 或 Grant accounts - Write 权限的应用则无法更改管理员或客户账户。完整详情（包括如何限制权限）请参阅 governance.md。

状态

Beta 版。已根据 Cisco Duo API 接口进行验证，目前正与使用该工具在自己的生产租户上运行的 MSP 合作伙伴一起，在每周的 Build Sessions 中进行验证。请在 compoundingteams.com/build-sessions 报名。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；40 多种 Agent）。兼容 MCP——可与任何支持 MCP 的 Agent 配合使用，包括 Hermes。已为 OpenClaw 做好准备（frontmatter 已预先配置，等待 OpenClaw 发布）。

由 Servosity 维护。采用 Apache-2.0 许可。使用 CLI Printing Press 构建。最后更新：2026-10-13。