mcp-argocd

mcp-argocd

mcp-argocd 是一个用于 Argo CD REST API 的 Model Context Protocol (MCP) 服务。它为 AI 助手提供 37 个工具、7 个资源和 7 个提示词，用于排查应用状态、同步、回滚、检查漂移、读取日志，以及管理 ApplicationSet、集群、项目和仓库。适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot 以及任何兼容 MCP 的客户端。它支持两种运行模式：允许写入，或锁定为只读模式（MCP_READ_ONLY=true），这样模型就不会获得这 9 个写入工具。

适用于 Argo CD 3.3+（任何安装方式：OSS、Akuity、OpenShift GitOps）。需要 API 令牌，无需访问集群。

支持 MCP 2026-07-28 规范（通常称为 MCP 2.0），并兼容 2025-11-25 客户端。

基于 FastMCP 4.x、httpx 和 Pydantic 构建。

安装： uvx mcp-argocd | PyPI | MCP Registry | 更新日志

uvx mcp-argocd                          # with writes
MCP_READ_ONLY=true uvx mcp-argocd       # locked read-only: write tools are not listed

一键安装

**提示：**如需配置其他 AI 助手（Claude Code、Windsurf、IntelliJ、Gemini CLI），请访问 Argo CD MCP 安装入口。

# with writes
claude mcp add argocd -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> -- uvx mcp-argocd
# locked read-only
claude mcp add argocd -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> -- uvx mcp-argocd

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": ["mcp-argocd"],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "<token>",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> argocd uvx mcp-argocd
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> argocd uvx mcp-argocd

{
  "servers": {
    "argocd": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-argocd"],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "<token>",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add argocd --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN=<token> -- uvx mcp-argocd
# locked read-only
codex mcp add argocd --env MCP_READ_ONLY=true --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN=<token> -- uvx mcp-argocd

uvx mcp-argocd            # run without installing
pip install mcp-argocd    # or install into an environment

获取 API 令牌

Argo CD 令牌来自具有 apiKey 能力的本地账户，或项目角色。

1. 在 argocd-cm 中添加本地账户：设置 accounts.ci-bot: apiKey。
2. 生成令牌：argocd account generate-token --account ci-bot --expires-in 24h。
3. 设置 ARGOCD_URL 和 ARGOCD_TOKEN。

只读所需的最低 RBAC：

p, role:mcp-ro, applications, get, */*, allow
p, role:mcp-ro, logs, get, */*, allow
p, role:mcp-ro, applicationsets, get, */*, allow
p, role:mcp-ro, projects, get, *, allow
p, role:mcp-ro, clusters, get, *, allow
p, role:mcp-ro, repositories, get, *, allow

兼容性

协议支持

支持 MCP 2026-07-28 规范（MCP 2.0），并兼容 2025-11-25 客户端。 基于 FastMCP 4.x 构建。回归测试使用固定为 2026-07-28 的内存 MCP 客户端列出全部 37 个工具。sse 传输方式已被 2026-07-28 规范弃用；它仍然可用，但会打印警告。服务不使用 roots、sampling、logging、elicitation 或资源订阅。

错误结果

预期的失败情况——应用不存在（404）、权限被拒绝（403）、写入请求触发只读保护——会返回带有 isError: true 的工具结果，而非成功封装。（在锁定的只读模式下，写入工具会被隐藏，因此调用此类工具会返回 Unknown tool 错误；以下封装是保护机制自身的响应，仅当客户端仍然调用写入工具时才会返回。）响应正文是 JSON 对象 {"error", "status_code"?, "body"?, "hint"?}，其中 hint 会在适用时指出纠正措施。响应正文是结果中经过美化格式处理的文本内容；结果不包含 structuredContent，因为严格的 MCP 客户端（TypeScript SDK）会根据工具的 outputSchema 验证 structuredContent，即使 isError 为 true 也会如此，否则会拒绝该错误。意外错误同样带有 isError: true，但会包含 TypeName: message 文本和记录的回溯信息。成功结果会在经过美化格式处理的文本旁携带相同的 JSON 对象作为 structuredContent，因此客户端可以读取任一内容。工具不声明 outputSchema：负载会不经类型处理地透传上游字段；每个工具都可以通过 output_schema= 选择性启用类型化架构。

工具（37 个）

资源（7）

服务器通过 MCP 资源提供经过整理的 GitOps 规则和指南。

• resource://rules/sync-safety — 同步安全规则。
• resource://rules/rollback — 回滚规则。
• resource://rules/gitops-change-flow — GitOps 变更流程。
• resource://rules/applicationsets — ApplicationSet 规则。
• resource://guides/status-triage — 状态排查指南。
• resource://guides/rbac — RBAC 和权限错误。
• resource://guides/api-token-setup — API 令牌设置。

提示词（7）

该服务提供 MCP 提示词，即客户端以斜杠命令形式呈现的多工具工作流模板。

• triage_application — 诊断状态降级或不同步的应用。
• diagnose_sync_failure — 判断上次同步失败的原因。
• review_drift — 检查不同步的应用并建议修复方法。
• safe_sync — 检查同步窗口、执行试运行，然后同步并等待。
• rollback_application — 检查自动同步后执行回滚。
• fleet_status — 报告集群及未处于已同步/健康状态的应用。
• inspect_applicationset — 比较生成的应用与现有应用。

使用示例

• 分诊：“为什么 payments 处于降级状态？”将运行 triage_application — 检查应用状态、异常节点、警告事件，然后查看 Pod 日志。
• 漂移：“prod 中有哪些内容发生了漂移？”将运行 review_drift — 列出不同步的应用并显示每项差异。
• 安全同步：“安全地同步 web”将运行 safe_sync — 检查同步窗口、执行试运行，然后同步并等待。
• 回滚：“将 api 回滚到上一个正常部署版本”将运行 rollback_application — 首先检查自动同步。
• 集群群组：“显示集群健康状况”将运行 fleet_status — 显示集群及不健康的应用。

安全注意事项

• 令牌范围：使用工作流所需的最低 RBAC 权限。只读角色需要 applications, get 和 logs, get。
• 只读模式：在你控制的启动配置中设置 MCP_READ_ONLY=true（或 ARGOCD_READ_ONLY=true），服务启动后即会锁定：9 个写入工具和写入工作流提示词不会被列出，调用这些工具会返回“Unknown tool”，且保护机制会拒绝任何仍到达服务的写入请求。运行时无法解除锁定——无论其他来源提供的是 false、.env 文件还是工具参数；任何非 false/0/no/off/空值都会锁定，且 --read-only 只能启用锁定。锁定强度取决于启动配置：应在用户无法编辑的位置设置该选项（例如 Claude Code managed-mcp.json 等受管 MCP 配置、容器、k8s 或 systemd 环境变量，或托管的 HTTP 部署）。自行启动服务的用户可以控制其环境。请同时使用只读 Argo CD RBAC 角色（applications, get；logs, get）。
• SSL 验证：默认启用。仅在受信任的网络中使用自签名证书时才禁用。
• 密钥清理：仓库、集群和项目负载中的凭据、集群 config 和角色 jwtTokens 都会被清理，即使 full=True 也不例外。
• MCP 工具注解：每个工具都声明 readOnlyHint、destructiveHint 和 idempotentHint。
• 不存储凭据：服务在启动时从环境变量读取令牌，且绝不持久化该令牌。
• 破坏性工具：argocd_sync_application、argocd_rollback_application、argocd_terminate_operation、argocd_delete_application、argocd_run_resource_action、argocd_delete_resource。

权限

CLI 和传输选项

uvx mcp-argocd                                   # stdio (default)
uvx mcp-argocd --transport streamable-http --port 9000
uvx mcp-argocd --transport sse                   # deprecated; prints a warning
uvx mcp-argocd --read-only --insecure

HTTP 传输会使用所有者的 Argo CD 令牌，向所有能够访问该端口的用户提供每个工具。Host/Origin 保护并非身份验证，因此绑定到非环回主机时必须提供 bearer 令牌：设置 ARGOCD_HTTP_BEARER_TOKEN（至少 16 个字符；客户端发送 Authorization: Bearer <token>）。未提供令牌时，服务拒绝在非环回主机上启动。

ARGOCD_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  uvx mcp-argocd --transport streamable-http --host 0.0.0.0 --port 9000

Docker

镜像默认启用锁定只读模式（MCP_READ_ONLY=true）；传入 -e MCP_READ_ONLY=false 可允许写入。

docker build -t mcp-argocd .

# stdio, locked read-only (the image default)
docker run --rm -i \
  -e ARGOCD_URL=https://argocd.example.com \
  -e ARGOCD_TOKEN=<token> \
  mcp-argocd

镜像以非 root 用户运行，默认使用 stdio；传入 --transport streamable-http --host 0.0.0.0（并设置 ARGOCD_HTTP_BEARER_TOKEN）即可通过 HTTP 提供服务。

FAQ

mcp-argocd 支持 MCP 2026-07-28（MCP 2.0）吗？ 支持。它支持 MCP 2026-07-28 规范（通常称为 MCP 2.0），并兼容 2025-11-25 客户端。

它与 argoproj-labs/mcp-for-argocd 有何不同？ argoproj-labs/mcp-for-argocd 是官方 TypeScript 服务，提供 15 个工具。mcp-argocd 则增加了 37 个工具，默认使用精简载荷，另外还提供 diff、回滚、终止、等待操作完成、ApplicationSet dry-run 和 RBAC 错误提示。

支持哪些 Argo CD 版本？ Argo CD 3.3 及更高版本。大多数工具也适用于 2.x；只有 run_resource_action 使用 3.x 端点。

需要 kubectl 或集群凭据吗？ 不需要。它使用 bearer token 通过 HTTPS 与 Argo CD API 通信，不会直接访问集群。

能否以只读模式运行 mcp-argocd，以防止助手同步或删除任何内容？ 可以。使用 MCP_READ_ONLY=true（或 ARGOCD_READ_ONLY=true）启动。届时，9 个写入工具和写入工作流提示词都不会列出，因此模型看不到它们；调用其中任一工具都会返回“Unknown tool”，且进程运行期间无法重新启用写入功能。请在你可控的启动配置中设置该变量，例如托管的 MCP 配置、容器或 systemd 环境变量，或者托管部署；因为自行启动服务的用户可以不设置该变量。

需要哪种令牌？ 需要在 ARGOCD_TOKEN 中提供 bearer token。可以使用具备 apiKey 能力的本地账户生成令牌，也可以使用项目角色令牌。它也会读取 ARGOCD_AUTH_TOKEN 和 ARGOCD_API_TOKEN。

为什么对一个已存在的应用收到 403？ 如果未传入 project，对于不存在的应用，Argo CD 会返回 403。传入 project 即可获得真实的 404。

能否只同步一个资源？ 可以。向 argocd_sync_application 传入 resources，并使用 [group:]kind:name[/namespace] 选择器。

可以回滚吗？ 可以。使用历史记录 ID 调用 argocd_rollback_application。自动同步开启时，该工具会拒绝执行，并告知如何将其关闭。

它如何控制响应大小？ 每个工具默认返回精简载荷，并在客户端分页列出内容。传入 full=True 可获取原始载荷。

支持哪些传输方式？ stdio、streamable-http 和 sse。sse 已被 2026-07-28 规范弃用，但仍可使用。

如何安装？ 运行 uvx mcp-argocd，或将其添加到 MCP 客户端配置中。

相关 MCP 服务

• mcp-gitlab — GitLab 集成（83 个工具、7 个资源、6 个提示词）
• mcp-atlassian-extended — Jira + Confluence 集成（22 个工具、15 个资源、5 个提示词）
• mcp-coda — Coda 集成（53 个工具、12 个资源、5 个提示词）

开发

git clone https://github.com/vish288/mcp-argocd.git
cd mcp-argocd
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

许可证

MIT — 详见 LICENSE。