playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

ArgoCD MCP server

Integrates with ArgoCD to enable natural language control of Kubernetes application deployments through a Python-based bridge that supports GitOps workflows.
Back to servers
Setup instructions
Provider
John Reilly Pospos
Release date
Mar 17, 2025
Language
Python
Stats
9 stars
View on GitHub

This MCP server integrates with the ArgoCD API, allowing AI assistants and language models to manage ArgoCD applications through natural language interactions. It handles authentication, application management, and provides a robust API client for ArgoCD operations.

Installation

Prerequisites

  • Python 3.12+
  • ArgoCD API token
  • ArgoCD instance with API access

Setup Process

# Clone the repository
git clone https://github.com/severity1/argocd-mcp.git
cd argocd-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e .

Starting the Server

The server is configured using environment variables:

Environment Variable Description Default Value
ARGOCD_TOKEN ArgoCD API token None
ARGOCD_API_URL ArgoCD API endpoint https://argocd.example.com/api/v1
ARGOCD_VERIFY_SSL Verify SSL certificates true

Starting Methods

# Using MCP dev tools (provides debugging tools)
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp dev server.py

# Using MCP run command
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp run server.py

# Standard method
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py

# With custom API URL and SSL verification disabled
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
export ARGOCD_VERIFY_SSL=false
uv run server.py

# Using a .env file
echo "ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
ARGOCD_VERIFY_SSL=false" > .env
uv run server.py

# Run in background
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py > server.log 2>&1 & echo $! > server.pid

Connecting with Claude

Using Claude Code CLI

# Add the MCP server
claude mcp add argocd-mcp "uv run $(pwd)/server.py"

# With token
claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py"

# Verify it was added
claude mcp list

Using Claude Desktop

Create a claude_desktop_config.json configuration file:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/argocd-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "ARGOCD_TOKEN": "your_argocd_token",
        "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
        "ARGOCD_VERIFY_SSL": "true"
      }
    }
  }
}

Replace paths and values with your actual configuration:

  • Full path to the uv executable (which uv on macOS/Linux or where uv on Windows)
  • Correct directory path to your argocd-mcp installation
  • Your ArgoCD API token and other environment variables

Available Tools

Session Tools

  • get_user_info: Retrieve current user's information

Settings Tools

  • get_settings: Get ArgoCD server settings (UI, OIDC, etc.)
  • get_plugins: Get information about configured ArgoCD plugins

Version Tools

  • get_version: Get ArgoCD API server version information

Application Management Tools

  • list_applications: Get all applications with filtering options
  • get_application_details: Get detailed information about a specific application
  • create_application: Create a new application
  • update_application: Update an existing application
  • delete_application: Delete an application
  • sync_application: Trigger a sync operation on an application

Usage Examples

Checking User Information

User: What's my user information in ArgoCD?

Claude: Let me retrieve your user information.

⏺ argocd-mcp:get_user_info (MCP)
  ⎿  {"loggedIn": true, "username": "devops-user", "iss": "argocd"}

You are logged in as 'devops-user'.

Getting ArgoCD Version

User: What version of ArgoCD is running on the server?

Claude: Let me check the ArgoCD version information.

⏺ argocd-mcp:get_version (MCP)
  ⎿  {
        "Version": "v2.9.3+5eaf684",
        "BuildDate": "2023-09-15T14:25:11Z",
        "GitCommit": "5eaf68452",
        "GitTreeState": "clean",
        "GoVersion": "go1.20.7",
        "Compiler": "gc",
        "Platform": "linux/amd64",
        "KustomizeVersion": "v5.1.1",
        "HelmVersion": "v3.12.3",
        "KubectlVersion": "v1.27.4",
        "JsonnetVersion": "v0.20.0"
      }

You're running ArgoCD v2.9.3, built on September 15, 2023. It's running on Linux (amd64) with Go 1.20.7, and includes Kustomize v5.1.1 and Helm v3.12.3.

Managing Applications

User: What applications do I have in the "production" project?

Claude: Let me list your applications in the production project.

⏺ argocd-mcp:list_applications (MCP)
  ⎿  {
        "items": [
          {
            "metadata": {
              "name": "frontend-app",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "api-service",
            },
            "status": {
              "sync": {"status": "OutOfSync"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "database",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Degraded"},
            }
          }
        ]
      }

You have 3 applications in the production project:
- frontend-app (Synced, Healthy)
- api-service (OutOfSync, Healthy)
- database (Synced, Degraded)

Syncing an Application

User: Sync the api-service application

Claude: I'll sync the api-service application for you.

⏺ argocd-mcp:sync_application (MCP)
  ⎿  {
        "resourcesResult": {
          "updated": ["Deployment/api-service"],
          "hooks": []
        },
        "status": "Syncing"
      }

Application sync initiated successfully. The sync operation is now in progress.

Troubleshooting

If you encounter issues:

  1. Check server logs (info logging is enabled by default)
  2. For SSL certificate issues with self-signed certificates: 
    # Disable SSL verification
export ARGOCD_VERIFY_SSL=false
uv run server.py
  3. Verify environment variables are set correctly: 
    # Show all current ArgoCD environment variables
env | grep ARGOCD
  4. If using mcp dev server.py, access the MCP Inspector at http://localhost:5173 for debugging

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "argocd-mcp" '{"command":"/path/to/uv","args":["--directory","/path/to/argocd-mcp","run","server.py"],"env":{"ARGOCD_TOKEN":"your_argocd_token","ARGOCD_API_URL":"https://your-argocd-server.com/api/v1","ARGOCD_VERIFY_SSL":"true"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "argocd-mcp": {
            "command": "/path/to/uv",
            "args": [
                "--directory",
                "/path/to/argocd-mcp",
                "run",
                "server.py"
            ],
            "env": {
                "ARGOCD_TOKEN": "your_argocd_token",
                "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
                "ARGOCD_VERIFY_SSL": "true"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "argocd-mcp": {
            "command": "/path/to/uv",
            "args": [
                "--directory",
                "/path/to/argocd-mcp",
                "run",
                "server.py"
            ],
            "env": {
                "ARGOCD_TOKEN": "your_argocd_token",
                "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
                "ARGOCD_VERIFY_SSL": "true"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later