Argo CD MCP Server: Complete Setup Guide & GitOps Workflows

Quick Answer

The Argo CD MCP server, maintained by Argo Project Labs at github.com/argoproj-labs/mcp-argocd, exposes Argo CD's application management capabilities to AI clients like Claude, Cursor, and any other MCP-compatible host. It lets you query application health, inspect Kubernetes resources, investigate sync failures, and explore GitOps state — all through natural language.

The fastest verified setup path: obtain an Argo CD API token, set two environment variables (ARGOCD_SERVER and ARGOCD_TOKEN), run the server binary or Docker image, and add it to your AI client's MCP configuration.

Argo CD MCP Server Setup: 60-Second Checklist

• Argo CD instance accessible (v2.x or later)
• Argo CD API token generated (user token or API key)
• ARGOCD_SERVER set to your Argo CD host (e.g., argocd.example.com)
• ARGOCD_TOKEN set to your auth token
• ARGOCD_INSECURE=true set if using self-signed TLS (dev only)
• MCP server binary built or Docker image pulled
• AI client (Claude Desktop, Cursor, etc.) configured to launch the server
• Connection verified — ask the AI to list applications

Who Maintains This and Its Project Status

The MCP server for Argo CD lives under Argo Project Labs (argoproj-labs), which is the official experimental and incubation space for the Argo Project. This is not a third-party community fork. The project is actively developed but should be considered experimental — production deployments require careful access control and monitoring.

If you find other community repositories advertising an "Argo CD MCP server," verify their source. This article covers only the argoproj-labs/mcp-argocd implementation.

Argo CD MCP Server Architecture

Understanding the data flow prevents configuration mistakes and security surprises.

┌─────────────────────────────────────────────────────────┐
│                    AI Client Host                       │
│  ┌───────────────────┐    ┌───────────────────────────┐ │
│  │  Claude Desktop / │    │   Cursor / Claude Code /  │ │
│  │   Claude Code     │    │   Other MCP-compatible    │ │
│  └────────┬──────────┘    └────────────┬──────────────┘ │
│           │  MCP Protocol (stdio)      │                 │
│           └──────────────┬─────────────┘                 │
│                          │                               │
│              ┌───────────▼────────────┐                  │
│              │  Argo CD MCP Server    │                  │
│              │  (argoproj-labs/       │                  │
│              │   mcp-argocd)          │                  │
│              │                        │                  │
│              │  - Tool definitions    │                  │
│              │  - Schema validation   │                  │
│              │  - Auth handling       │                  │
│              └───────────┬────────────┘                  │
└──────────────────────────┼──────────────────────────────┘
                           │  Argo CD REST/gRPC API
                           │  (ARGOCD_TOKEN auth)
                    ┌──────▼──────────────┐
                    │   Argo CD Server    │
                    │   (argocd-server)   │
                    │                     │
                    │  Applications       │
                    │  Resources          │
                    │  Sync Status        │
                    │  Health State       │
                    └──────┬──────────────┘
                           │
              ┌────────────▼────────────┐
              │  Kubernetes Cluster(s)  │
              │  (target environments)  │
              └─────────────────────────┘

Key point: The MCP server is a thin translation layer. It converts MCP tool calls into Argo CD API requests and returns structured responses back to the AI client. The AI never touches Kubernetes directly — everything flows through Argo CD's access controls.

The default transport is stdio, which means the AI client spawns the MCP server as a subprocess. This is the most secure mode: no network port exposed, process lifetime tied to the client session.

Prerequisites

Installation

Option 1: Build from Source

git clone https://github.com/argoproj-labs/mcp-argocd.git
cd mcp-argocd
go build -o mcp-argocd ./cmd/mcp-argocd

Verify the build:

./mcp-argocd --help

Option 2: Docker

Pull the image from the repository's published registry (check the repository's README and GitHub Packages for the current image tag):

docker pull ghcr.io/argoproj-labs/mcp-argocd:latest

Run a quick connectivity test:

docker run --rm \
  -e ARGOCD_SERVER=argocd.example.com \
  -e ARGOCD_TOKEN=your-token-here \
  ghcr.io/argoproj-labs/mcp-argocd:latest

Always check the repository's README and releases page for the current recommended image tag. The latest tag may point to an unstable build during active development.

Authentication: Getting an Argo CD Token

The MCP server authenticates with Argo CD using a bearer token. There are two practical ways to get one.

Method 1: Argo CD CLI

# Log in and capture the token
argocd login argocd.example.com --username admin --password your-password

# Extract the stored token
cat ~/.config/argocd/config | grep token

Method 2: API Key (Recommended for Automation)

Create a dedicated Argo CD service account, bind it to a limited RBAC role, then generate an API token:

# Create an API token for a specific account
argocd account generate-token --account mcp-reader

This requires the mcp-reader account to exist in your Argo CD configuration (typically defined in the argocd-cm ConfigMap).

Setting Credentials

export ARGOCD_SERVER=argocd.example.com
export ARGOCD_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# For self-signed certs in dev/test environments only:
export ARGOCD_INSECURE=true

Never hardcode tokens in configuration files committed to version control. Use environment variables, secrets managers, or your OS keychain.

Configuring AI Clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "argocd": {
      "command": "/path/to/mcp-argocd",
      "env": {
        "ARGOCD_SERVER": "argocd.example.com",
        "ARGOCD_TOKEN": "your-token-here",
        "ARGOCD_INSECURE": "false"
      }
    }
  }
}

For Docker-based deployment:

{
  "mcpServers": {
    "argocd": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ARGOCD_SERVER=argocd.example.com",
        "-e", "ARGOCD_TOKEN=your-token-here",
        "ghcr.io/argoproj-labs/mcp-argocd:latest"
      ]
    }
  }
}

Restart Claude Desktop after saving. Look for the MCP tools icon in the chat interface to confirm the server loaded successfully.

Cursor

In Cursor settings, navigate to Extensions → MCP Servers and add:

{
  "argocd": {
    "command": "/path/to/mcp-argocd",
    "env": {
      "ARGOCD_SERVER": "argocd.example.com",
      "ARGOCD_TOKEN": "your-token-here"
    }
  }
}

Claude Code

claude mcp add argocd /path/to/mcp-argocd \
  --env ARGOCD_SERVER=argocd.example.com \
  --env ARGOCD_TOKEN=your-token-here

Verifying the Connection

After configuring your client, ask it: "List all Argo CD applications." If the MCP server is connected and authenticated, you should receive a list of your applications. If you get an error, jump to the Common Errors section.

You can also use the MCP Inspector to test the server independently before connecting it to a production AI client — it lets you call individual tools and inspect raw responses.

Argo CD MCP Server Tools

The following tools are exposed by the argoproj-labs/mcp-argocd server based on the repository's current implementation. Tool availability may expand as the project develops — always check the repository's tool definitions for the authoritative list.

Important: The actual tool surface evolves as the project matures. Some write operations (sync, rollback) may be added in future releases. Before assuming a tool exists, verify against the repository source. Never assume write capabilities without confirming from the codebase.

Read vs. Write distinction matters. Even read tools can expose sensitive manifest data, secret references, and environment-specific configuration. Treat every tool call as a privileged operation.

Real-World Argo CD MCP Workflows

Here are practical examples of how developers are using the Argo CD MCP server in real GitOps workflows.

Checking Application Health Across Environments

"Show me the health and sync status of all applications in the production project."

The AI calls list_applications, filters by project, and returns a structured summary. This is faster than switching between the Argo CD UI and terminal during an incident.

Typical use case: Morning standup health check — ask the AI to summarize which apps are degraded or out-of-sync before the team's daily sync call.

Investigating a Failed Sync

"Application checkout-service is OutOfSync. What resources are causing the sync failure?"

The AI calls get_application to retrieve the sync status, then get_application_resource_tree to identify which specific Kubernetes resources have sync errors. It can then correlate the resource tree with the source repository details.

This workflow saves significant time compared to navigating the Argo CD UI manually, especially when the resource tree has dozens of objects.

Inspecting Live Kubernetes Resources

"Show me the live manifest of the checkout-service Deployment in the production namespace."

Using get_resource, the MCP server fetches the live cluster state of that specific resource. The AI can compare it against what Argo CD expects from Git — instantly surfacing configuration drift.

Production caution: Live manifests can contain sensitive data. Ensure your AI client session is properly secured and logged.

Diagnosing Deployment Problems (Incident Response)

During an incident, a typical AI-assisted investigation flow:

1. "List all unhealthy applications" → list_applications filtered by health status
2. "Get details of the failing app" → get_application to check sync source and target
3. "Show the resource tree" → get_application_resource_tree to find which pods/services are unhealthy
4. "Show the live manifest of the failing Pod" → get_resource to inspect resource state
5. "What project does this app belong to?" → get_project to confirm RBAC boundaries

AI clients can chain these calls automatically within a single conversation, dramatically accelerating root-cause analysis compared to manual CLI commands.

Reviewing GitOps State Before a Release

"Which applications are currently out-of-sync in the staging environment?"

Pre-release review becomes conversational. Instead of running argocd app list and grepping, you ask the AI and get a formatted response with the relevant details surfaced.

AI-Assisted DevOps Onboarding

New team members can ask the AI to explain the resource structure of applications, which namespaces they deploy to, and what Git repositories back each application — without needing Argo CD CLI access configured locally. Access is controlled by the shared team token scoped to read-only operations.

Argo CD MCP Server Security Best Practices

Connecting an AI model to your GitOps control plane is a high-privilege operation. Apply these practices without exception.

Use Least-Privilege Tokens

Create a dedicated Argo CD account for MCP access with only the permissions it actually needs:

# In argocd-rbac-cm ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    p, role:mcp-reader, applications, get, */*, allow
    p, role:mcp-reader, applications, list, */*, allow
    p, role:mcp-reader, projects, get, *, allow
    p, role:mcp-reader, projects, list, *, allow
    g, mcp-reader-account, role:mcp-reader
  policy.default: role:readonly

# In argocd-cm ConfigMap — register the account
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  accounts.mcp-reader: apiKey

Then generate the token:

argocd account generate-token --account mcp-reader

Credential Storage

• Never store ARGOCD_TOKEN in plaintext config files committed to Git
• Use OS-level secret storage (macOS Keychain, Linux secret-tool) for local development
• In CI/CD or Kubernetes deployments, use Kubernetes Secrets with restrictive RBAC
• Rotate tokens regularly — treat them with the same care as cloud provider credentials

Limit AI Client Scope

• Only expose MCP servers to AI clients that genuinely need Argo CD access
• Run one MCP server per AI client session where possible — avoid shared long-running servers accessible by multiple users
• Consider running with production MCP deployment practices to understand the full operational picture

Audit and Monitor API Usage

Argo CD logs all API requests. Enable audit logging and monitor for:

• Unusual volume of get_resource calls (bulk manifest extraction)
• Access patterns outside business hours
• Access to production environments from development MCP configurations

# Check Argo CD server logs for API activity from your MCP token
kubectl logs -n argocd deployment/argocd-server | grep "mcp-reader"

Understand What AI Models See

Every tool response is sent to the AI model's context window. This means:

• Application manifests including environment variable names (not values if using external secrets, but the keys themselves)
• Kubernetes resource specifications
• Git repository URLs and target revisions
• Cluster and namespace names

Do not connect AI clients to environments where exposure of this metadata violates your compliance requirements without reviewing the data handling policies of your AI provider.

For a comprehensive view of MCP security principles, see MCP security best practices and the dedicated guide on how to secure an MCP server.

Deploying in Kubernetes

For team-shared access, deploy the MCP server as a Kubernetes workload.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-argocd
  namespace: argocd
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-argocd
  template:
    metadata:
      labels:
        app: mcp-argocd
    spec:
      containers:
        - name: mcp-argocd
          image: ghcr.io/argoproj-labs/mcp-argocd:latest
          env:
            - name: ARGOCD_SERVER
              value: "argocd-server.argocd.svc.cluster.local"
            - name: ARGOCD_TOKEN
              valueFrom:
                secretKeyRef:
                  name: mcp-argocd-credentials
                  key: token
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "200m"
              memory: "128Mi"

apiVersion: v1
kind: Secret
metadata:
  name: mcp-argocd-credentials
  namespace: argocd
type: Opaque
stringData:
  token: "your-mcp-reader-token-here"

When running inside the cluster, set ARGOCD_SERVER to the internal service DNS name to avoid unnecessary network egress.

Common Argo CD MCP Server Errors

Debugging Checklist

1. Run the binary manually with the same environment variables — does it start without errors?
2. Test Argo CD API directly: curl -H "Authorization: Bearer $ARGOCD_TOKEN" https://$ARGOCD_SERVER/api/v1/applications
3. Check client-side logs: Claude Desktop writes MCP server stderr to its log files
4. Use MCP Inspector to test individual tool calls in isolation — this quickly narrows down whether the issue is the server, the credentials, or the AI client configuration
5. Verify network: from the same machine/pod where the MCP server runs, confirm you can reach the Argo CD API endpoint

Limitations to Know Before You Deploy

Experimental status. This is an argoproj-labs project, not a core Argo CD component. APIs and tool definitions may change between releases without backward compatibility guarantees.

Read-heavy by design. The current tool set focuses on inspection and visibility. If you need to trigger syncs, rollbacks, or application creation through MCP, those capabilities are not confirmed in the current implementation — verify before building workflows that depend on write operations.

No built-in rate limiting. AI models in agentic mode can call tools rapidly in loops. There is no built-in throttle between the MCP server and the Argo CD API. A misbehaving agent could generate significant API load. Monitor Argo CD server metrics when running agentic workflows.

Context window limits. Large resource trees returned by get_application_resource_tree can be substantial. For applications managing hundreds of resources, the response may approach AI model context limits. This is a practical constraint for large monorepo-style Argo CD setups.

Single user token model. The server uses one token for all tool calls in a session. There is no per-user token delegation — if multiple team members share an MCP deployment, they all use the same Argo CD identity. Design your RBAC accordingly.

Production Deployment Checklist

• Dedicated Argo CD service account with scoped RBAC (not admin)
• Read-only RBAC policy unless write operations are explicitly required
• Token stored in Kubernetes Secret or secrets manager — not in plaintext config
• Token rotation policy defined and scheduled
• Argo CD audit logging enabled and aggregated to your log management system
• MCP server deployed with resource limits (CPU/memory)
• Network policy restricting MCP server to Argo CD API only
• Alert on anomalous API call volume from the MCP service account
• AI client configured with the minimum necessary tools
• Reviewed running MCP in production for operational guidance

Recent Changes and Ecosystem Context

The argoproj-labs/mcp-argocd project is under active development. The Argo Project's decision to build an official MCP server reflects the broader trend of GitOps tooling becoming AI-accessible — following patterns established by the Kubernetes MCP server and other CNCF-adjacent projects.

Watch the repository's releases page and changelog for updates on:

• New tool additions (sync operations, application creation)
• Transport changes (HTTP/SSE support in addition to stdio)
• Integration with Argo CD's OIDC authentication model
• Official integration documentation for specific AI clients

Key Takeaways

The Argo CD MCP server from Argo Project Labs gives AI clients structured, authenticated access to your GitOps control plane. The setup is straightforward — two environment variables and a binary path — but the security implications require careful attention.

Start with a read-only token scoped to non-production environments. Validate workflows with MCP Inspector before connecting to production. Apply the RBAC configuration shown in this article, and treat every AI client connection as a privileged operator session.

The real productivity gain is in conversational incident response and application inspection — asking an AI to summarize sync failures, walk you through a resource tree, or identify degraded applications across environments. These workflows are immediately practical with the current read-focused tool set.

For organizations already invested in Argo CD and AI-assisted development workflows, this MCP server provides a well-scoped integration point that keeps GitOps guardrails intact while making your deployment data accessible to AI reasoning.