/ 目录 / 演练场 / ArgoCD
● 官方 argoproj-labs 🔑 需要你的密钥

ArgoCD

作者 argoproj-labs · argoproj-labs/mcp-for-argocd

从 Claude 检查、比较和同步 ArgoCD 应用 —— GitOps 集群状态,无需切换 kubectl 上下文。

ArgoProj Labs 的 MCP 封装了 ArgoCD API:列出应用、查看同步/健康状态、比较期望态 vs 实际态、触发同步和读取应用清单。token 默认只读用于可观测性,仅在你明确需要同步或覆盖时才可写。

为什么要用

核心特性

实时演示

实际使用效果

argocd.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "argocd",
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "argocd": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-for-argocd"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add argocd -- uvx mcp-for-argocd

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: ArgoCD

查找已偏离同步的 ArgoCD 应用

👤 运行 GitOps 的平台/SRE 团队 ⏱ ~20 min intermediate

何时使用: 每周:哪些集群中的哪些应用处于 OutOfSync 或 Degraded 状态,原因是什么?

前置条件
  • 具有读取权限的 ArgoCD API token — argocd account generate-token --account <read-only-user>
  • ArgoCD 服务器 URLARGOCD_SERVER=argocd.my.company.com
步骤
  1. 列出应用及其状态
    列出所有 ArgoCD 应用。对于每个应用:名称、项目、同步状态、健康状态、最后同步时间。✓ 已复制
    → 完整清单
  2. 关注偏差
    筛选 syncStatus != 'Synced' 或 health != 'Healthy' 的应用。按上次同步以来的时间排序。✓ 已复制
    → 问题应用列表
  3. 比较特定应用
    对于应用 <name>,显示期望态(git)和实际态之间的差异。哪些资源不同步?✓ 已复制
    → 资源级差异

结果: 周报告,标识哪些应用需要关注及原因。

注意事项
  • 由合法的仅运行时资源引起的偏差(如 HPA 扩展的副本数) — 在 Application spec 中配置 ignoreDifferences,排除在运行时变化的字段
搭配使用: notion

审查并应用特定应用的同步

👤 推进变更的 DevOps 工程师 ⏱ ~15 min intermediate

何时使用: 一个 PR 合并到 main;ArgoCD 显示应用为 OutOfSync 状态,等待你的批准。

前置条件
  • 对目标项目有同步权限的 token — Role with applications, sync, <project>/* allowed
步骤
  1. 检查待处理的变更
    对于应用 <name>,显示差异。哪些资源改变了,影响范围是什么?✓ 已复制
    → 具体差异
  2. 检查源提交
    期望态指向哪个提交 SHA?显示 GitHub 提交消息和 PR。✓ 已复制
    → 提交 + PR 上下文
  3. 首先使用 prune=false 进行同步
    为 <name> 触发同步,设置 prune=false、dryRun=false。等待完成,显示最终状态。✓ 已复制
    → Sync Succeeded;health Healthy

结果: 经过事前审查的部署,没有意外;删除仅在明确情况下通过 prune 发生。

注意事项
  • 使用 prune=true 同步可能删除你仍然需要的资源 — 始终以 prune=false 开始;仅在确认命名空间中不存在手动创建的资源时才启用 prune
搭配使用: github

紧急回滚到之前的 git 修订版本

👤 不良部署事件期间的 SREs ⏱ ~15 min advanced

何时使用: 部署已发布,错误飙升,你需要回滚到上次已知的良好状态。

步骤
  1. 获取当前状态和历史
    对于应用 <name>,显示当前修订版本和最后 5 个已部署修订版本及时间戳。✓ 已复制
    → 历史表
  2. 选择回滚目标
    2 次同步之前的修订版本是什么?确认其 SHA 与事件发生前的 git 提交相匹配。✓ 已复制
    → 目标 SHA 已确定
  3. 回滚
    将 <name> 同步到修订版本 <SHA>,设置 prune=false。监视直到 Healthy。完成后在 Teams 中发布。✓ 已复制
    → 应用已回滚 + 通知已发送

结果: 清晰的回滚并留有审计踪迹,通常在 5 分钟内完成。

注意事项
  • 仅回滚应用,但数据库迁移已经向前运行 — 数据库迁移需要自己的回滚计划;有时用修复'向前推进'比针对已变更的 schema 回滚代码更安全
搭配使用: sentry · ms-teams

构建跨集群应用清单

👤 管理多个集群的平台团队 ⏱ ~20 min intermediate

何时使用: 你在中心辐射模型中运行 ArgoCD,并希望获得扁平列表:'哪些应用运行在哪里'。

步骤
  1. 列出 ArgoCD 管理的集群
    列出在 ArgoCD 中注册的所有集群及其名称和服务器 URL。✓ 已复制
    → 集群清单
  2. 将应用映射到集群
    对于每个应用,显示其目标集群和命名空间。按集群分组。✓ 已复制
    → 按集群的应用列表
  3. 标记异常的部署位置
    有应用部署在意外的集群中吗(例如,'仅生产'应用在开发集群中)?标记并说明原因。✓ 已复制
    → 异常列表

结果: 最新的应用分布映射,对审计和容量规划有用。

注意事项
  • 陈旧的集群条目 —— 凭据已删除但集群仍在列表中 — 定期验证每个集群是否可达;删除陈旧的

组合

与其他 MCP 搭配,撬动十倍杠杆

argocd + github

交叉引用导致 Argo 同步的 PR

对于应用 <name>,显示当前修订版本 SHA;获取引入它的 GitHub PR 并总结变更。✓ 已复制
argocd + sentry

关联 Argo 同步与部署后的错误飙升

应用 <name> 在 14:02 同步;之后 Sentry 错误是否飙升?如果是,显示引入的主要问题。✓ 已复制
argocd + ms-teams

将同步/回滚事件发布到 Teams 频道

在任何手动同步应用 <name> 后,向 Teams #deploys 频道发布消息,包含修订版本 SHA 和触发者。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_applications project?, selector? 列出应用清单 free
get_application name 特定应用的详细状态 free
get_application_diff name, revision? 预览同步会改变什么 free
sync_application name, revision?, prune?, dryRun?, resources? 应用待处理的变更 free (triggers cluster work)
get_application_resource_tree name 检查应用拥有的实时资源 free
list_clusters 跨集群清单 free

成本与限制

运行它的成本

API 配额
受 ArgoCD 服务器容量限制;实际限制约 ~10 req/s
每次调用 Token 数
应用列表:500–3000 tokens。Diff:最高 5000。
费用
免费 —— ArgoCD 是开源的,你只需付费用于托管它的基础设施。
提示
缓存应用列表;使用选择器(project、label)缩小查询范围而非列出所有内容。

安全

权限、密钥、影响范围

最小权限: 对应用和集群的读权限用于只读会话
凭据存储: ARGOCD_AUTH_TOKENARGOCD_SERVER 在环境变量中
数据出站: 仅调用你的 ArgoCD 服务器
切勿授予: admin 无原因对所有项目的同步权限 account:update

故障排查

常见错误与修复

401 Unauthenticated

ARGOCD_AUTH_TOKEN 已过期或被撤销。通过 argocd account generate-token 重新生成。

验证: argocd account get-user-info --auth-token $ARGOCD_AUTH_TOKEN
403 Permission denied on sync

角色缺少 applications, sync, <project>/* 权限。更新 AppProject 或账户角色。

Sync 卡在 Progressing 超过 10 分钟

通常是资源卡住 —— 检查 resource-tree 查找失败的 hook 或卡住的 controller;可能需要在集群中手动干预。

Diff 在每次同步时显示意外的偏差

Controller 在运行时修改字段。为这些字段添加 ignoreDifferences 到 Application spec。

替代方案

ArgoCD 对比其他方案

替代方案何时用它替代权衡
Flux MCP你使用 Flux 而不是 ArgoCD 用于 GitOps不同的 GitOps 引擎;CLI 优先模型
Kubernetes MCP (raw kubectl)你需要直接集群访问而不需要 GitOps 抽象命令式 —— 破坏了 GitOps 对托管应用的目的

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills