io.github.asklokesh/argocd-mcp-server

Official

by asklokesh

Argocd

MCP server for ArgoCD GitOps continuous delivery integration

Integrates ArgoCD for GitOps-based continuous delivery workflows.

README.md12 KBView on GitHub

ArgoCD MCP Server

<div align="center">

Argocd Mcp Server

</div>

A Model Context Protocol (MCP) server for integrating ArgoCD GitOps continuous delivery tool with GenAI applications, enabling intelligent Kubernetes deployment management.

Features

Comprehensive ArgoCD API Coverage:
- Application Management: Create, sync, delete, rollback applications
- Project Management: Configure projects, roles, and policies
- Repository Management: Add/remove Git repositories, Helm charts
- Cluster Management: Register and manage Kubernetes clusters
- Sync Operations: Manual/auto sync, sync windows, hooks
- Health Monitoring: Application health, sync status, resource tree
- RBAC Management: Users, roles, policies, JWT tokens
- GitOps Workflows: Automated deployments from Git commits
- Multi-tenancy: Namespace isolation, project restrictions
- Application Sets: Template-based multi-cluster deployments
Authentication Methods:
- JWT Token authentication
- API Token authentication
- OIDC/OAuth2 integration
- LDAP authentication support
Enterprise Features:
- Multi-cluster support
- Disaster recovery workflows
- Progressive delivery (Canary, Blue-Green)
- Automated rollback on failures
- Audit logging and compliance
- Resource optimization
- Secret management integration

Installation

bash

pip install argocd-mcp-server

Or install from source:

bash

git clone https://github.com/asklokesh/argocd-mcp-server.git
cd argocd-mcp-server
pip install -e .

Configuration

Create a .env file or set environment variables:

env

# ArgoCD Connection
ARGOCD_SERVER=argocd.example.com
ARGOCD_AUTH_TOKEN=your_auth_token
ARGOCD_INSECURE=false

# Optional Settings
ARGOCD_GRPC_WEB=true
ARGOCD_TIMEOUT=30
ARGOCD_CLIENT_CERT=/path/to/cert.pem
ARGOCD_CLIENT_KEY=/path/to/key.pem

# Multi-Cluster Support
ARGOCD_PROD_SERVER=argocd-prod.example.com
ARGOCD_PROD_TOKEN=prod_token

ARGOCD_DEV_SERVER=argocd-dev.example.com
ARGOCD_DEV_TOKEN=dev_token

Quick Start

Basic Usage

python

from argocd_mcp import ArgoCDMCPServer

# Initialize the server
server = ArgoCDMCPServer()

# Start the server
server.start()

Claude Desktop Configuration

Add to your Claude Desktop config:

json

{
  "mcpServers": {
    "argocd": {
      "command": "python",
      "args": ["-m", "argocd_mcp.server"],
      "env": {
        "ARGOCD_SERVER": "argocd.example.com",
        "ARGOCD_AUTH_TOKEN": "your_auth_token"
      }
    }
  }
}

Available Tools

Application Management

List Applications

python

{
  "tool": "argocd_list_applications",
  "arguments": {
    "project": "default",
    "namespace": "argocd"
  }
}

Create Application

python

{
  "tool": "argocd_create_application",
  "arguments": {
    "name": "my-app",
    "project": "default",
    "source": {
      "repoURL": "https://github.com/org/repo.git",
      "path": "manifests",
      "targetRevision": "main"
    },
    "destination": {
      "server": "https://kubernetes.default.svc",
      "namespace": "production"
    },
    "syncPolicy": {
      "automated": {
        "prune": true,
        "selfHeal": true
      }
    }
  }
}

Sync Application

python

{
  "tool": "argocd_sync_application",
  "arguments": {
    "name": "my-app",
    "prune": true,
    "force": false,
    "strategy": {
      "hook": {
        "force": true
      }
    }
  }
}

Get Application Status

python

{
  "tool": "argocd_get_application_status",
  "arguments": {
    "name": "my-app",
    "refresh": true
  }
}

Rollback Application

python

{
  "tool": "argocd_rollback_application",
  "arguments": {
    "name": "my-app",
    "revision": "abc123"
  }
}

Project Management

Create Project

python

{
  "tool": "argocd_create_project",
  "arguments": {
    "name": "production",
    "description": "Production applications",
    "sourceRepos": ["https://github.com/org/*"],
    "destinations": [
      {
        "server": "https://kubernetes.default.svc",
        "namespace": "prod-*"
      }
    ],
    "clusterResourceWhitelist": [
      {"group": "*", "kind": "*"}
    ]
  }
}

Repository Management

Add Repository

python

{
  "tool": "argocd_add_repository",
  "arguments": {
    "url": "https://github.com/org/repo.git",
    "name": "my-repo",
    "type": "git",
    "username": "git-user",
    "password": "git-token",
    "insecure": false
  }
}

Add Helm Repository

python

{
  "tool": "argocd_add_helm_repository",
  "arguments": {
    "url": "https://charts.example.com",
    "name": "my-charts",
    "type": "helm",
    "username": "helm-user",
    "password": "helm-password"
  }
}

Cluster Management

Add Cluster

python

{
  "tool": "argocd_add_cluster",
  "arguments": {
    "name": "production-cluster",
    "server": "https://k8s-prod.example.com",
    "config": {
      "bearerToken": "cluster-token",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "base64-encoded-ca"
      }
    }
  }
}

Application Sets

Create ApplicationSet

python

{
  "tool": "argocd_create_applicationset",
  "arguments": {
    "name": "multi-cluster-app",
    "generators": [
      {
        "clusters": {},
        "selector": {
          "matchLabels": {
            "environment": "production"
          }
        }
      }
    ],
    "template": {
      "metadata": {
        "name": "{{cluster}}-app"
      },
      "spec": {
        "project": "default",
        "source": {
          "repoURL": "https://github.com/org/repo.git",
          "path": "{{cluster}}"
        },
        "destination": {
          "server": "{{server}}",
          "namespace": "default"
        }
      }
    }
  }
}

Health and Monitoring

Get Application Health

python

{
  "tool": "argocd_get_application_health",
  "arguments": {
    "name": "my-app"
  }
}

Get Resource Tree

python

{
  "tool": "argocd_get_resource_tree",
  "arguments": {
    "name": "my-app"
  }
}

Advanced Configuration

Multi-Cluster GitOps

python

from argocd_mcp import ArgoCDMCPServer, ClusterConfig

# Configure multiple ArgoCD instances
clusters = {
    "production": ClusterConfig(
        server="argocd-prod.example.com",
        auth_token="prod_token",
        default_namespace="argocd"
    ),
    "staging": ClusterConfig(
        server="argocd-staging.example.com",
        auth_token="staging_token",
        default_namespace="argocd-staging"
    ),
    "development": ClusterConfig(
        server="argocd-dev.example.com",
        auth_token="dev_token",
        default_namespace="argocd-dev"
    )
}

server = ArgoCDMCPServer(clusters=clusters, default_cluster="production")

Progressive Delivery

python

# Configure progressive delivery strategies
progressive_config = {
    "canary": {
        "steps": [
            {"setWeight": 10},
            {"pause": {"duration": "5m"}},
            {"setWeight": 30},
            {"pause": {"duration": "5m"}},
            {"setWeight": 50},
            {"pause": {"duration": "5m"}},
            {"setWeight": 100}
        ]
    },
    "blueGreen": {
        "activeService": "app-active",
        "previewService": "app-preview",
        "autoPromotionEnabled": false
    }
}

server = ArgoCDMCPServer(progressive_config=progressive_config)

Disaster Recovery

python

from argocd_mcp import ArgoCDMCPServer, DisasterRecoveryConfig

dr_config = DisasterRecoveryConfig(
    backup_enabled=True,
    backup_schedule="0 2 * * *",  # Daily at 2 AM
    backup_location="s3://backups/argocd",
    restore_priority=["production", "staging", "development"]
)

server = ArgoCDMCPServer(dr_config=dr_config)

Integration Examples

See the examples/ directory for complete integration examples:

basic_gitops.py - Basic GitOps workflows
multi_cluster_deployment.py - Multi-cluster application deployment
progressive_delivery.py - Canary and blue-green deployments
disaster_recovery.py - Backup and restore workflows
genai_gitops.py - AI-powered GitOps automation
security_scanning.py - Integration with security tools

Security Best Practices

Use service accounts with minimal permissions
Enable RBAC with proper policies
Implement network policies for cluster isolation
Use sealed secrets or external secret operators
Enable audit logging for compliance
Implement admission controllers for policy enforcement
Regular security scanning of images and manifests

Error Handling

The server provides detailed error information:

python

try:
    result = server.execute_tool("argocd_sync_application", {
        "name": "my-app"
    })
except ArgoCDError as e:
    print(f"ArgoCD error: {e.error_code} - {e.message}")
    if e.error_code == "OutOfSync":
        print("Application is out of sync")
    elif e.error_code == "ComparisonError":
        print("Error comparing application state")

Performance Optimization

Use application sets for similar apps
Enable resource caching in ArgoCD
Implement sync windows to control deployment times
Use webhook notifications instead of polling
Optimize manifest generation with Helm/Kustomize

Troubleshooting

Common Issues

Sync failures
- Check application logs
- Verify repository access
- Review resource quotas
Authentication errors
- Verify token validity
- Check RBAC policies
- Review server connectivity
Performance issues
- Check ArgoCD server resources
- Review application count
- Optimize manifest size

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE file for details

Install

Configuration

Environment variables

ARGOCD_API_KEYrequiredsecret

API Key for ARGOCD

ARGOCD_API_URL

API URL for ARGOCD

claude_desktop_config.json

{
  "mcpServers": {
    "argocd-mcp-server": {
      "command": "uvx",
      "args": [
        "argocd-mcp-server"
      ],
      "env": {
        "ARGOCD_API_KEY": "<YOUR_ARGOCD_API_KEY>",
        "ARGOCD_API_URL": "<YOUR_ARGOCD_API_URL>"
      }
    }
  }
}