Argo CD MCP Server

The Argo CD MCP Server is an implementation of the Model Context Protocol (MCP) that enables AI assistants to interact with Argo CD via natural language. It provides a bridge between AI clients (like VS Code, Cursor, or Claude Desktop) and the Argo CD API, allowing assistants to manage clusters, projects, applications, and resources.

Key features include:

• Transport Protocols: Supports stdio and HTTP stream transport modes.
• Full API Integration: Provides comprehensive access to Argo CD resources and operations.
• AI-Ready Tools: Pre-configured tools designed specifically for natural language interaction.

The project includes a Makefile to run the server over the HTTP transport. You can run it in production-style (build then run) or in development mode (run from source with tsx watch).

• make run: Builds and runs the HTTP server.
• make dev: Runs from source with hot reloading.

You can override the port using the PORT variable.

make run PORT=4000

make run    # build, then run the HTTP server (production-style)
make dev    # run from source with hot reloading (tsx watch)
make run PORT=4000

To develop on the Argo CD MCP Server, clone the repository, install dependencies using pnpm, and start the development server with hot reloading. Once running, the server can be used by MCP clients like Visual Studio Code.

# Clone and enter the repository
git clone https://github.com/argoproj-labs/mcp-for-argocd.git
cd mcp-for-argocd

# Install dependencies
pnpm install

# Start development server with hot reloading
pnpm run dev

To use the Argo CD MCP server with Cursor, create a .cursor/mcp.json file in your project directory. This configuration uses npx to run the latest version of the server via the stdio transport. You must provide your Argo CD instance URL and API token as environment variables.

Prerequisites:

• Node.js (v18 or higher recommended)
• Argo CD instance with API access
• Argo CD API token

After configuration, start a conversation in Cursor's Agent mode to begin using the tools.

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

By default, the HTTP transport uses session IDs and in-memory maps. This causes issues in distributed environments (like Kubernetes with HPA) where requests might be routed to different replicas without sticky sessions.

To run in Stateless mode, use the --stateless flag. In this mode:

• No Mcp-Session-Id is required or returned.
• Any replica can handle any request.
• Requirement: ArgoCD credentials (Base URL and API Token) must be supplied on every request via environment variables or x-argocd-base-url / x-argocd-api-token headers.
• Session-level SSE (GET /mcp and DELETE /mcp) is not supported.

Usage via CLI:

node dist/index.js http --stateless

Usage via Docker:

docker run -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  argoprojlabs/mcp-for-argocd http --stateless

To use the Argo CD MCP server with Claude Desktop, create a claude_desktop_config.json configuration file. This configuration uses npx to run the server via the stdio transport. You must provide your Argo CD instance URL and API token as environment variables.

After creating the file, ensure Claude Desktop is configured to use this configuration file in its settings.

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

If you need to update the TypeScript type definitions to match a newer Argo CD API version:

1. Download the swagger.json file from the ArgoCD release page.
2. Place swagger.json in the root of the argocd-mcp project.
3. Run the type generation command:

   pnpm run generate-types

   This overwrites src/types/argocd.d.ts.
4. Manually update src/types/argocd-types.ts to export the required types from the newly generated file.

To use the Argo CD MCP server with VS Code, create a .vscode/mcp.json file in your project directory. This configuration uses npx to run the server via the stdio transport. You must provide your Argo CD instance URL and API token as environment variables.

After configuration, start a conversation with an AI assistant in VS Code that supports MCP.

{
  "servers": {
    "argocd-mcp-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

The V1alpha1ApplicationStatus interface provides real-time observability into an Argo CD application. It includes:

• Health: health (current health state) and conditions (list of observed conditions, often errors or warnings).
• Sync State: sync (observed live vs desired state) and history (previous sync revisions).
• Resources: resources (list of managed Kubernetes resources and their individual status).
• Metadata: observedAt and reconciledAt timestamps, and controllerNamespace.
• Summary: summary containing externalURLs and images used by the application.

Use V1alpha1SCMProviderGeneratorFilter to restrict which repositories are discovered by the generator. Multiple filters are combined using a logical AND.

Available filters:

• branchMatch: Regex for branch names.
• labelMatch: Regex for repository labels.
• repositoryMatch: Regex for repository names.
• pathsExist: Array of paths that must exist in the repo.
• pathsDoNotExist: Array of paths that must not exist in the repo.