ArgoCD MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Kubernetes applications via ArgoCD using GitOps principles. Designed for AI assistants to perform secure, production-grade ArgoCD operations with deep observability, validation, and guided workflows.

---

✨ Features

🎯 Application Management

• Create, update, and delete ArgoCD applications
• List applications across clusters with health and sync status
• Get detailed application information including resource breakdown
• Validate application configurations before deployment
• View application events and audit trails

🚀 Deployment & Operations

• Sync applications to desired state (with dry-run support)
• Get deployment diffs to preview changes
• Monitor sync operations in real-time
• Rollback to previous versions with impact analysis
• Prune orphaned resources
• Hard and soft refresh operations
• Cancel ongoing deployments

📦 Repository Management

• Onboard GitHub repositories via HTTPS or SSH
• Validate repository connections before onboarding
• List and manage registered repositories
• Delete repositories from ArgoCD
• Generate Kubernetes secret manifests for disaster recovery
• Secure credential handling (never exposed to LLM)

🏢 Project Management (Multi-Tenancy)

• Create ArgoCD projects with RBAC policies
• Define source repository patterns (wildcards supported)
• Configure destination clusters and namespaces
• Whitelist/blacklist cluster and namespace resources
• Generate AppProject YAML manifests

🔍 Monitoring & Debugging

• Real-time application health metrics
• Smart log analysis with automatic error detection
• Cluster-wide health overview
• Active sync operation tracking
• Deployment event streams
• Comprehensive troubleshooting workflows

📚 Guided Workflows (Prompts)

• Repository onboarding: Step-by-step GitHub integration
• Full deployment: End-to-end from repo to running app
• Debugging: Automated issue diagnosis with recommendations
• Rollback: Guided recovery with history and impact preview
• Project setup: Multi-tenancy configuration assistant
• Deployment validation: Comprehensive post-deployment checks

---

🏗️ Architecture

---

📦 Quick Start

Prerequisites

Requirement	Description
ArgoCD Server	Running ArgoCD instance (v2.x)
ArgoCD Token	API authentication token
Docker	For containerized deployment (recommended)
Python 3.12+	For local installation
Git Credentials	HTTPS token or SSH key for repo onboarding

Docker Quick Start

# Pull and run with default configuration
docker pull sandeep2014/talkops-mcp:argocd-mcp-server-latest

docker run --rm -it \
  -p 8765:8765 \
  -v ~/.ssh/id_ed25519:/app/.ssh/id_rsa:ro \
  -e ARGOCD_SERVER_URL="https://argocd.example.com" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e SSH_PRIVATE_KEY_PATH=/app/.ssh/id_rsa \
  -e MCP_ALLOW_WRITE="true" \
  sandeep2014/talkops-mcp:argocd-mcp-server-latest

Connect Your MCP Client

{
  "mcpServers": {
    "argocd-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8765/sse",
      "description": "ArgoCD MCP Server for GitOps application management"
    }
  }
}

---

🔒 Security Considerations

Practice	Description
Read-Only Mode	Default mode prevents all mutating operations
Credential Isolation	Secrets never passed to LLM
Write Access Control	Granular operation permissions
TLS Verification	Secure ArgoCD connections
Dry-run Support	Preview changes before applying
Environment Variables	Best practices for secret management

---

📁 Project Structure

argocd-mcp-server/
├── argocd_mcp_server/         # Main package
│   ├── tools/                 # MCP Tools (29 total)
│   │   ├── application_manager/   # Application lifecycle tools
│   │   ├── deployment_executor/   # Deployment and sync tools
│   │   ├── repository_mgmt/       # Repository management tools
│   │   └── project_mgmt/          # Project management tools
│   ├── resources/             # MCP Resources (5 total)
│   ├── prompts/               # MCP Prompts (7 total)
│   ├── services/              # Business logic layer
│   ├── server/                # FastMCP server setup
│   ├── static/                # Static documentation
│   └── config.py              # Configuration management
├── scripts/                   # Helper scripts
├── tests/                     # Test suite
└── pyproject.toml             # Project configuration

---

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• FastMCP for the Python MCP framework
• ArgoCD for GitOps application delivery

---

Next Steps

• ⚙️ Configuration - Complete setup and environment variables
• 🛠️ Tools - Available MCP tools reference
• 📁 Resources and Prompts - MCP resources and prompts
• 📖 Examples - Usage patterns and workflows