ArgoCD MCP Server: a safety layer between an AI agent and a GitOps cluster

ArgoCD MCP Server

Give an AI agent real operational control of your production GitOps cluster, without giving it the ability to quietly delete it. Read-only by default, dry-run on every write, and destructive operations that make you type the application name twice.

At a Glance

The integration suite is not mocked: CI stands up a Kind cluster, installs ArgoCD, and drives the real API, including the delete and prune paths.

Why This Exists

"95% of MCP servers are garbage."

We built this because we were tired of:

The Empty Error Message Problem. You sync an app. It fails. The error? "Sync failed." Thanks, very helpful. Meanwhile, the actual cause is buried across three different Kubernetes events, two pod logs, and a misconfigured HPA that nobody told you about. Our diagnose_sync_failure tool aggregates all of that into one coherent analysis.

The "Oops, I Deleted Production" Problem. Most MCP servers treat every operation the same. Read a deployment? Same as deleting a namespace! We implement defense-in-depth: read-only by default, writes require explicit opt-in, destructive operations require typing the resource name twice. Because at 3 AM, you don't need an LLM with root access to your production cluster.

The YAML Fatigue Problem. When you have 47 applications across 12 clusters, the ArgoCD UI becomes a slideshow. We built this for SREs who live in terminals and need answers fast: "What's broken in prod?" should return an answer, not a loading spinner.

The Context Window Problem. MCP servers that dump entire manifests into the context are doing it wrong. We use progressive disclosure: simple status first, details on request, full manifests only when you explicitly ask. Your context window is precious real estate.

Quick Demo

Illustrative example. The conversation below is a hand-written demonstration of how an agent would use these tools, not a transcript of a real session. Tool names, parameters, and responses match what the server actually returns; the surrounding chat is for illustration only.

You: What applications are failing in production?

Claude: Let me check the production applications for you.

[calls list_applications(health_status="Degraded", project="prod")]

Found 2 application(s):

- payment-service [prod] health=Degraded sync=OutOfSync dest=payments@https://prod.k8s...
- notification-api [prod] health=Degraded sync=Synced dest=notifications@https://prod.k8s...

The payment-service is both unhealthy AND out of sync. Want me to diagnose what's wrong?

You: Why is payment-service broken?

Claude: I'll run a full diagnosis.

[calls diagnose_sync_failure(name="payment-service")]

Diagnosis for 'payment-service':

Found 4 issue(s):
  - Application is out of sync (revision: abc123f)
  - [SyncError] Failed to sync: resource payment-deployment: container crashed
  - Image pull failed: ImagePullBackOff for payments:v2.3.1
  - Found 2 unhealthy resources in resource tree
    - Deployment/payment-deployment: Container crashloopbackoff
    - Pod/payment-deployment-7f8b9-x2k4j: CrashLoopBackOff

Suggestions:
  - Verify image exists and registry credentials are configured
  - Check pod logs for application startup errors
  - Run get_application_diff to see pending changes

The image tag v2.3.1 doesn't seem to exist. Can you verify it was pushed to the registry?

You: Show me what would change if I sync it

Claude: [calls get_application_diff(name="payment-service")]

Diff for application 'payment-service':

Resources to UPDATE (3):
  ~ Deployment/payment-deployment
  ~ ConfigMap/payment-config
  ~ Service/payment-service

Resources in sync: 12

The sync would update the deployment (probably the image tag fix), update the
config, and touch the service. Want me to run the sync?

You: Yes, sync it

Claude: [calls sync_application(name="payment-service", dry_run=false)]

Sync initiated for 'payment-service'
Revision: HEAD
Prune: false

Use get_application_status to monitor progress.

I'll check the status in a moment to confirm it's progressing.

Philosophy

Progressive Disclosure

Not everything needs to be visible all the time. We tier our tools:

This isn't bureaucracy. This is respecting that production systems deserve more friction than rm -rf /.

Dry-Run by Default

Every write operation defaults to preview mode. You have to explicitly say "yes, really do this" before anything changes. We learned this lesson from too many "I thought that was staging" incidents.

Agent-Friendly Error Messages

# Bad (what most tools return)
Error: exit status 1

# Good (what we return)
ArgoCD API error (403): Application payment-service not found in project 'default'

Suggestions:
  - Check if application exists: list_applications(project="prod")
  - Verify you have access to the target project

Errors should tell you what went wrong AND what to try next.

Quick Start

Installation

# Clone the repository
git clone https://github.com/peopleforrester/mcp-k8s-observability-argocd-server
cd mcp-k8s-observability-argocd-server

# Install with uv
uv sync

Claude Desktop / Claude Code Configuration

Add to your Claude configuration (~/.claude.json for Claude Code):

{
  "mcpServers": {
    "argocd": {
      "type": "stdio",
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-k8s-observability-argocd-server",
        "argocd-mcp"
      ],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "your-api-token",
        "ARGOCD_INSECURE": "false"
      }
    }
  }
}

Note: Replace /path/to/uv with the full path to your uv binary (run which uv to find it).

See examples/ for more configuration options including multi-cluster setups.

Docker

# Build the image
docker build -t argocd-mcp-server .

# Run with environment variables
docker run -e ARGOCD_URL=https://argocd.example.com \
           -e ARGOCD_TOKEN=your-token \
           argocd-mcp-server:latest

Running Directly

# Set environment variables
export ARGOCD_URL=https://argocd.example.com
export ARGOCD_TOKEN=your-token

# Run the server
uv run argocd-mcp

Security Model

We don't just check permissions. We make it hard to do the wrong thing.

Enabling Write Operations (Carefully)

# Enable writes (still blocks destructive operations)
export MCP_READ_ONLY=false

# Enable destructive operations (delete, prune) - DANGER ZONE
export MCP_DISABLE_DESTRUCTIVE=false

For the full security model deep-dive, see docs/SECURITY.md.

Tool Reference

Tier 1: Essential Read Operations (Always Available)

Tier 2: Write Operations (Require MCP_READ_ONLY=false)

Tier 3: Destructive Operations (Require explicit confirmation)

For detailed parameter documentation, see docs/TOOLS.md.

Example Conversations

"What applications are failing in production?"

list_applications(health_status="Degraded", project="prod")

"Why is my-app not syncing?"

diagnose_sync_failure(name="my-app")

"Deploy the latest changes to staging"

sync_application(name="my-app", dry_run=false)

"Show me what would change if I sync"

get_application_diff(name="my-app")

"What was deployed last week?"

get_application_history(name="my-app", limit=20)

Configuration Reference

Environment Variables

Multi-Instance Configuration

For managing multiple ArgoCD instances (multi-cluster, multi-environment):

# Primary instance
export ARGOCD_URL=https://argocd-prod.example.com
export ARGOCD_TOKEN=prod-token

# Additional instances can be configured via the multi-env example.
# See examples/claude-desktop-multi-env.json

Development

Prerequisites

• Python 3.11, 3.12, 3.13, or 3.14
• uv (recommended) or pip
• Docker (for container builds)
• Kind 0.33+ (for local Kubernetes testing)

Setup

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check src tests
uv run mypy src

# Build Docker image
docker build -t argocd-mcp-server .

Testing with Kind

Important: Kubernetes 1.36 removed cgroup v1 support entirely. A node on a cgroup v1 host will not start. (cgroup v1 had been in maintenance mode since 1.31; 1.35 was the last release to support it.) Check your cgroup version:

docker info | grep "Cgroup Version"

• Cgroup Version: 2 - Use Kubernetes 1.37 (default in Kind 0.33+)
• Cgroup Version: 1 - Pin Kubernetes 1.35.x or earlier, or upgrade Docker/WSL2 to cgroup v2

# Auto-detect cgroup version and create cluster
./scripts/setup-test-cluster.sh

# Or manually with specific version:
# For cgroups v2 (recommended):
kind create cluster --name argocd-mcp-test --image kindest/node:v1.37.0

# For cgroups v1 hosts (last supported release):
kind create cluster --name argocd-mcp-test --image kindest/node:v1.35.8

# Install ArgoCD
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for ArgoCD to be ready
kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd

# Get ArgoCD admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Port forward
kubectl port-forward svc/argocd-server -n argocd 8080:443

Architecture

argocd-mcp-server/
├── src/argocd_mcp/
│   ├── server.py           # Entrypoint: FastMCP instance, lifespan, ServerContext, registration
│   ├── config.py           # Configuration management (pydantic-settings)
│   ├── tools/
│   │   ├── read.py         # Tier-1 read-only handlers
│   │   ├── write.py        # Tier-2 write handlers (require MCP_READ_ONLY=false)
│   │   ├── destructive.py  # Tier-3 destructive handlers (require confirmation)
│   │   ├── params.py       # Pydantic parameter models for every tool
│   │   └── _safety.py      # Shared destination-cluster guard
│   ├── resources/
│   │   └── applications.py # MCP resources: argocd://instances, argocd://security
│   └── utils/
│       ├── client.py       # ArgoCD API client with retry logic and secret masking
│       ├── safety.py       # Confirmation patterns, rate limiting
│       └── logging.py      # Structured logging, audit trail
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests (Kind cluster)
├── docs/
│   ├── TOOLS.md            # Detailed tool documentation
│   └── SECURITY.md         # Security model deep-dive
├── examples/               # Example configurations
└── Dockerfile              # Multi-stage container build

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache 2.0 - See LICENSE for details.

Acknowledgments

Built on the shoulders of:

• MCP Specification - The protocol that makes this possible
• containers/kubernetes-mcp-server - Inspiration for safety patterns
• argoproj-labs/mcp-for-argocd - The official (but less opinionated) option

Built by SREs, for SREs. Because production deserves better than "LGTM, ship it."