ArgoCD MCP — Use Cases, Install & Live Demo

Why use it

Key features

List/inspect ArgoCD applications across projects
Show sync status, health, and last-sync info
Diff live cluster state vs desired git state
Trigger sync (with prune/force options) when authorized
Read app manifests without cluster kubectl access

Live Demo

What it looks like in practice

argocd.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "argocd",
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "argocd": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-for-argocd"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use ArgoCD

Find ArgoCD apps that have drifted out of sync

👤 Platform / SRE teams running GitOps ⏱ ~20 min intermediate

When to use: Weekly: which apps in which clusters are OutOfSync or Degraded, and why?

Prerequisites

ArgoCD API token with read scope — argocd account generate-token --account <read-only-user>
ArgoCD server URL — ARGOCD_SERVER=argocd.my.company.com

Flow

List apps with status

List all ArgoCD apps. For each: name, project, sync status, health status, last sync time.✓ Copied

→ Full inventory
Focus on drift

Filter to apps with syncStatus != 'Synced' or health != 'Healthy'. Rank by time since last sync.✓ Copied

→ Problem apps list
Diff a specific app

For app <name>, show the diff between desired (git) and live. What resources are out of sync?✓ Copied

→ Resource-level diff

Outcome: A weekly drift report identifying which apps need attention and why.

Pitfalls

Drift caused by a legitimate runtime-only resource (e.g. HPA scaled replicas) — Configure ignoreDifferences in the Application spec to exclude fields that change at runtime

Combine with: notion

Review and apply a sync for a specific application

👤 DevOps engineers promoting changes ⏱ ~15 min intermediate

When to use: A PR merged to main; ArgoCD shows the app as OutOfSync pending your approval.

Prerequisites

Token with sync permission on the target project — Role with applications, sync, <project>/* allowed

Flow

Inspect the pending change

For app <name>, show the diff. What resources change, what's the blast radius?✓ Copied

→ Concrete diff
Check the source commit

What commit SHA does the desired state point at? Show the GitHub commit message and PR.✓ Copied

→ Commit + PR context
Sync with prune=false first

Trigger sync for <name> with prune=false, dryRun=false. Wait for completion, show final status.✓ Copied

→ Sync Succeeded; health Healthy

Outcome: A deploy with prior-review, not a surprise; deletion-by-prune only happens explicitly.

Pitfalls

Sync with prune=true can delete resources you still need — Always start with prune=false; only enable prune when you've confirmed no manually-created resources exist in the namespace

Combine with: github

Emergency rollback to a previous git revision

👤 SREs during a bad-deploy incident ⏱ ~15 min advanced

When to use: A deploy went out, errors spiked, and you need to roll back to last known good.

Flow

Get current + history

For app <name>, show current revision and the last 5 deployed revisions with timestamps.✓ Copied

→ History table
Pick the rollback target

What was the revision 2 syncs ago? Confirm its SHA matches the git commit before the incident started.✓ Copied

→ Target SHA identified
Rollback

Sync <name> to revision <SHA> with prune=false. Watch until Healthy. Post in Teams when done.✓ Copied

→ App reverted + notification sent

Outcome: A clean rollback with an audit trail, typically under 5 minutes.

Pitfalls

Rolling back only the app but DB migration already ran forward — DB migrations need their own rollback plan; sometimes 'roll forward' with a fix is safer than rolling back code against mutated schema

Combine with: sentry · ms-teams

Build a cross-cluster app inventory

👤 Platform teams managing many clusters ⏱ ~20 min intermediate

When to use: You run ArgoCD in a hub-spoke model and want a flat list: 'which apps run where'.

Flow

List clusters ArgoCD manages

List all clusters registered in ArgoCD with their name and server URL.✓ Copied

→ Cluster inventory
Map apps to clusters

For each app, show its destination cluster and namespace. Group by cluster.✓ Copied

→ Per-cluster app list
Flag unusual placements

Any app deployed in an unexpected cluster (e.g. 'prod-only' app in a dev cluster)? Flag with reason.✓ Copied

→ Anomaly list

Outcome: An up-to-date map of what runs where, useful for audits and capacity planning.

Pitfalls

Stale cluster entries — secrets removed but cluster still listed — Periodically verify each cluster is reachable; remove stale ones

Combinations

Pair with other MCPs for X10 leverage

argocd + github

Cross-reference Argo sync with the PR that caused it

For app <name>, show the current revision SHA; fetch the GitHub PR that introduced it and summarize the change.✓ Copied

argocd + sentry

Correlate an Argo sync with a post-deploy error spike

App <name> synced at 14:02; did Sentry errors spike after that? If yes, show the top issue introduced.✓ Copied

argocd + ms-teams

Post sync/rollback events to a Teams channel

After any manual sync of app <name>, post a message to Teams #deploys with revision SHA and who triggered it.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_applications	project?, selector?	Inventory apps	free
get_application	name	Detailed state of a specific app	free
get_application_diff	name, revision?	Preview what a sync would change	free
sync_application	name, revision?, prune?, dryRun?, resources?	Apply pending changes	free (triggers cluster work)
get_application_resource_tree	name	Inspect the live resources an app owns	free
list_clusters		Cross-cluster inventory	free

Cost & Limits

What this costs to run

API quota: Bounded by your ArgoCD server capacity; practical limit ~10 req/s
Tokens per call: App list: 500–3000 tokens. Diff: up to 5000.
Monetary: Free — ArgoCD is open source, you only pay for the infra hosting it.
Tip: Cache app list; use selectors (project, label) to narrow queries rather than listing everything.

Security

Permissions, secrets, blast radius

Minimum scopes: read on applications, clusters for read-only sessions

Credential storage: ARGOCD_AUTH_TOKEN and ARGOCD_SERVER in env

Data egress: Calls to your ArgoCD server only

Never grant: admin sync on all projects without reason account:update

Sync permission can deploy arbitrary manifests — treat it like production write access.
Use project-scoped RBAC policies instead of cluster-admin for automation accounts.

Troubleshooting

Common errors and fixes

401 Unauthenticated

ARGOCD_AUTH_TOKEN expired or revoked. Regenerate via argocd account generate-token.

Verify: argocd account get-user-info --auth-token $ARGOCD_AUTH_TOKEN

403 Permission denied on sync

Role lacks applications, sync, <project>/* permission. Update AppProject or account role.

Sync stuck in Progressing for >10 min

Usually a stuck resource — check resource-tree for a failing hook or a stuck controller; may need manual intervention in-cluster.

Diff shows unexpected drift on every sync

Controllers mutating fields at runtime. Add ignoreDifferences to the Application spec for those fields.

Alternatives

ArgoCD vs others

Alternative	When to use it instead	Tradeoff
Flux MCP	You use Flux instead of ArgoCD for GitOps	Different GitOps engine; CLI-first model
Kubernetes MCP (raw kubectl)	You want direct cluster access without GitOps abstraction	Imperative — defeats the purpose of GitOps for managed apps

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills