Skip to main content

ArgoCD MCP Server

Python 3.12+ MCP License: Apache 2.0 ArgoCD GitHub Discord

If you've run ArgoCD in production, you know the drill: something's broken, and you're bouncing between the UI, the CLI, and your Git repo trying to piece together what went wrong. Sync failures, drift, RBAC headaches—it's powerful stuff, but diagnosing it often feels like archaeology. AI assistants should be able to help, but until now they've had no structured way to talk to ArgoCD.

This server fixes that. It exposes the full ArgoCD lifecycle—discovery, configuration, deployment, monitoring, rollback—as MCP tools, resources, and prompts. Your assistant can onboard repos, validate manifests, preview diffs, run syncs, and troubleshoot failures the way a seasoned platform engineer would. A few things we care about:

Safety first. Every mutating operation sits behind a write-access toggle (MCP_ALLOW_WRITE). Dry-runs are built in. We validate before we touch anything. You can run this in read-only mode and let the assistant observe and debug without ever modifying your GitOps state.

The full lifecycle, not just sync. Most ArgoCD integrations stop at "trigger a sync." We cover repo onboarding (HTTPS and SSH), project multi-tenancy, app creation, drift detection, pruning, and root-cause analysis when deployments fail.

Operational knowledge baked in. The server ships with workflow guides for repo onboarding, full deployments, debugging, and emergency rollbacks—exposed as MCP prompts. The assistant doesn't just call APIs; it follows the patterns you'd use yourself.

What You Can Do With It​

Application Management​

Create, update, and delete applications. List them across clusters with health and sync status. Drill into a single app for resource breakdown, events, and audit trails. Validate configs before you deploy—no more "oops" moments when a typo slips through.

Deployment & Operations​

Sync to desired state (with dry-run when you want to peek first). Get diffs before you apply. Monitor syncs in real time. Roll back to a previous revision or a specific Git hash. Prune orphaned resources. Hard and soft refresh when ArgoCD's cache is lagging. Cancel a deployment mid-flight if something looks wrong.

Repository Management​

Onboard GitHub repos via HTTPS or SSH. Validate the connection before you register it. List and manage what's already there. Credentials live in env vars—they never get passed to the LLM.

Projects & Multi-Tenancy​

Create ArgoCD projects with RBAC. Scope source repos and destination clusters. Whitelist or blacklist namespaces and resources. Generate AppProject YAML when you want to commit your setup as code.

Monitoring & Debugging​

Real-time health metrics, sync status, and deployment events. Log analysis that surfaces errors instead of dumping raw output. Cluster-wide health overview. The kind of visibility you need when you're tracking down why something went sideways.

Guided Workflows​

Prompts for repository onboarding, end-to-end deployment, debugging, rollback, and project setup. The assistant follows these when you ask in natural language—"deploy my app from GitHub to production" or "help me debug payment-service."

How It's Built​

The server is layered: tools and prompts on top, business logic in the middle, ArgoCD API at the bottom. Your MCP client connects over HTTP or stdio, discovers tools and resources, and the service layer translates calls into ArgoCD API requests. Auth and credentials stay on the server side.

Quick Start​

You'll need a running ArgoCD instance (v2.x), an API token, and Docker or Python 3.12+. For repo onboarding, you'll need Git credentials (HTTPS token or SSH key).

Docker (recommended):

docker pull talkopsai/argocd-mcp-server:latest

docker run --rm -it \
  -p 8770:8770 \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e MCP_PORT=8770 \
  -e MCP_PATH="/mcp" \
  -e ARGOCD_INSECURE="true" \
  -e GIT_PASSWORD="your-github-pat" \
  -e MCP_ALLOW_WRITE="true" \
  -e GIT_USERNAME="your-github-username" \
  talkopsai/argocd-mcp-server:latest
note

Use host.docker.internal when your ArgoCD is port-forwarded locally (kubectl port-forward svc/argocd-server -n argocd 8080:443).

Point your MCP client at it (e.g. in mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "argocd-mcp-server": {
      "url": "http://localhost:8770/mcp",
      "disabled": false,
      "disabledTools": []
    }
  }
}

Security​

We default to read-only. Set MCP_ALLOW_WRITE=true only when you actually need the assistant to deploy, sync, or modify things. Keep credentials in environment variables—never pass them into the chat. Use dry-run and diff previews before applying changes. And in production, leave TLS verification on; skip it only for local dev.

Project Layout​

argocd-mcp-server/
├── argocd_mcp_server/
│   ├── tools/           # 29 MCP tools (apps, deploy, repos, projects)
│   ├── resources/       # Real-time streams and static data
│   ├── prompts/         # Deployment, repo, and debug workflows
│   ├── services/        # ArgoCD API client
│   ├── server/          # FastMCP setup
│   └── utils/
├── scripts/             # e.g. fetch_argocd_token.py
├── tests/
└── pyproject.toml

Python 3.12+, FastMCP, ArgoCD v2.x API. HTTP/SSE or stdio. Docker and uv for packaging.

Next Steps​