mcp-argocd

# mcp-argocd

[![PyPI version](https://img.shields.io/pypi/v/mcp-argocd)](https://pypi.org/project/mcp-argocd/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-argocd)](https://pypi.org/project/mcp-argocd/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-argocd)](https://pypi.org/project/mcp-argocd/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/vish288/mcp-argocd/actions/workflows/tests.yml/badge.svg)](https://github.com/vish288/mcp-argocd/actions/workflows/tests.yml)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)

<!-- mcp-name: io.github.vish288/mcp-argocd -->

**mcp-argocd** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the Argo CD REST API. It gives AI assistants **37 tools**, **7 resources**, and **7 prompts** to triage application status, sync, roll back, inspect drift, read logs, and manage ApplicationSets, clusters, projects, and repositories. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Works with Argo CD 3.3+ (any install: OSS, Akuity, OpenShift GitOps). Needs an API token, no cluster access.

Supports the MCP 2026-07-28 specification, often called MCP 2.0, and stays compatible with 2025-11-25 clients.

Built with [FastMCP](https://github.com/jlowin/fastmcp) 4.x, [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).

**Install:** `uvx mcp-argocd` | [PyPI](https://pypi.org/project/mcp-argocd/) | [MCP Registry](https://registry.modelcontextprotocol.io) | [Changelog](https://github.com/vish288/mcp-argocd/releases)

## 1-Click Installation

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-install?server=mcp-argocd&install=cursor)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-argocd&install=vscode)

> **Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the **[Argo CD MCP Installation Gateway](https://vish288.github.io/mcp-install?server=mcp-argocd)**.

<details>
<summary><b>Manual Setup Guides (Click to expand)</b></summary>
<br/>

> Prerequisite: Install `uv` first. [Install uv](https://docs.astral.sh/uv/getting-started/installation/).

### Claude Code

```bash
claude mcp add argocd -- uvx mcp-argocd
```

### Windsurf & IntelliJ

**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
**IntelliJ:** Add to `Settings | Tools | MCP Servers`

```json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": ["mcp-argocd"],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "<token>"
      }
    }
  }
}
```

### Gemini CLI

The repo ships `gemini-extension.json`; install it with the Gemini CLI extension flow.

### pip / uv

```bash
uvx mcp-argocd            # run without installing
pip install mcp-argocd    # or install into an environment
```

</details>

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ARGOCD_URL` | Yes | - | Base URL including any path prefix. Also reads `ARGOCD_SERVER`. |
| `ARGOCD_TOKEN` | Yes | - | Bearer token. Also reads `ARGOCD_AUTH_TOKEN`, `ARGOCD_API_TOKEN`. |
| `ARGOCD_READ_ONLY` | No | `false` | `true` blocks the 9 write tools before any API call |
| `ARGOCD_TIMEOUT` | No | `30` | Request timeout in seconds |
| `ARGOCD_SSL_VERIFY` | No | `true` | `false` skips SSL verification (`ARGOCD_INSECURE=true` is an alias) |
| `ARGOCD_APP_NAMESPACE` | No | - | Default `appNamespace` for apps-in-any-namespace installs |

## Getting an API token

Argo CD tokens come from a local account with the `apiKey` capability, or from a project role.

1. Add a local account in `argocd-cm`: set `accounts.ci-bot: apiKey`.
2. Generate a token: `argocd account generate-token --account ci-bot --expires-in 24h`.
3. Set `ARGOCD_URL` and `ARGOCD_TOKEN`.

Minimum read-only RBAC:

```
p, role:mcp-ro, applications, get, */*, allow
p, role:mcp-ro, logs, get, */*, allow
p, role:mcp-ro, applicationsets, get, */*, allow
p, role:mcp-ro, projects, get, *, allow
p, role:mcp-ro, clusters, get, *, allow
p, role:mcp-ro, repositories, get, *, allow
```

## Compatibility

| Component | Supported |
|---|---|
| Argo CD | 3.3+ (OSS, Akuity, OpenShift GitOps); most tools also work on 2.x |
| Python | 3.10, 3.11, 3.12, 3.13, 3.14 |
| Transports | stdio, streamable-http, sse (deprecated) |
| MCP spec | 2026-07-28 (MCP 2.0); compatible with 2025-11-25 |

## Protocol support

Supports the MCP 2026-07-28 specification (MCP 2.0) and stays compatible with 2025-11-25 clients.
Built on FastMCP 4.x. A regression test lists all 37 tools with an in-memory MCP client pinned to
2026-07-28. The `sse` transport is
deprecated by the 2026-07-28 specification; it still works and prints a warning. The server uses
no roots, sampling, logging, elicitation, or resource subscriptions.

## Tools (37)

| Category | Count |
|---|---|
| Applications — read | 14 |
| Applications — write | 8 |
| ApplicationSets | 3 |
| Projects | 2 |
| Clusters | 3 |
| Repositories | 3 |
| Server and account | 4 |

<details>
<summary><b>Full tool reference (Click to expand)</b></summary>

### Applications — read

- `argocd_list_applications` — List applications with slim rows; filter by sync, health, destination.
- `argocd_get_application` — Get one application: spec, sync/health, conditions, operation, counts.
- `argocd_get_resource_tree` — Get the live resource tree as slim nodes.
- `argocd_get_managed_resources` — Get live-vs-desired diffs for managed resources.
- `argocd_get_resource` — Get a single managed resource's live manifest.
- `argocd_get_manifests` — Get the rendered desired manifests for a revision.
- `argocd_get_application_events` — Get Kubernetes events for an application.
- `argocd_get_pod_logs` — Get container logs; never follows.
- `argocd_get_application_history` — Get deployment history, newest first.
- `argocd_get_revision_metadata` — Get commit metadata for a revision.
- `argocd_get_operation` — Get the current or last sync operation.
- `argocd_wait_for_operation` — Poll until an operation is terminal, gone, or times out.
- `argocd_get_sync_windows` — Get sync windows and whether the app can sync now.
- `argocd_list_resource_actions` — List the custom actions available on a resource.

### Applications — write

- `argocd_sync_application` — Sync an application; prune and force can delete or recreate resources.
- `argocd_rollback_application` — Roll back to a prior deployment history entry.
- `argocd_terminate_operation` — Terminate the running sync operation.
- `argocd_create_application` — Create an application from flattened parameters.
- `argocd_patch_application` — Patch an application; the one tool for every update.
- `argocd_delete_application` — Delete an application.
- `argocd_run_resource_action` — Run a custom resource action, such as restart.
- `argocd_delete_resource` — Delete a single managed resource so the controller recreates it.

### ApplicationSets

- `argocd_list_applicationsets` — List ApplicationSets with slim rows.
- `argocd_get_applicationset` — Get one ApplicationSet and the status of its generated apps.
- `argocd_generate_applicationset` — Dry-run the generators to preview generated apps; creates nothing.

### Projects

- `argocd_list_projects` — List projects with slim rows.
- `argocd_get_project` — Get a project's repos, destinations, and roles.

### Clusters

- `argocd_list_clusters` — List clusters with connection state, versions, and counts.
- `argocd_get_cluster` — Get one cluster by name or server URL.
- `argocd_invalidate_cluster_cache` — Invalidate a cluster's cached resources.

### Repositories

- `argocd_list_repositories` — List repositories; credentials are never returned.
- `argocd_get_repository_refs` — Get a repository's branches and tags.
- `argocd_list_repository_apps` — List the application paths discoverable in a repository.

### Server and account

- `argocd_get_version` — Get the Argo CD server version and bundled tool versions.
- `argocd_get_userinfo` — Get the authenticated identity.
- `argocd_can_i` — Check whether the account may perform a resource/action.
- `argocd_get_settings` — Get server settings and enabled features.

</details>

## Resources (7)

The server exposes curated GitOps rules and guides as MCP resources.

- `resource://rules/sync-safety` — Sync Safety Rules.
- `resource://rules/rollback` — Rollback Rules.
- `resource://rules/gitops-change-flow` — GitOps Change Flow.
- `resource://rules/applicationsets` — ApplicationSet Rules.
- `resource://guides/status-triage` — Status Triage Guide.
- `resource://guides/rbac` — RBAC and Permission Errors.
- `resource://guides/api-token-setup` — API Token Setup.

## Prompts (7)

The server provides MCP prompts — multi-tool workflow templates clients surface as slash commands.

- `triage_application` — Diagnose a Degraded or OutOfSync application.
- `diagnose_sync_failure` — Classify why the last sync failed.
- `review_drift` — Review OutOfSync apps and recommend a fix.
- `safe_sync` — Check sync windows, dry-run, then sync and wait.
- `rollback_application` — Roll back with the auto-sync check.
- `fleet_status` — Report clusters and apps that are not Synced/Healthy.
- `inspect_applicationset` — Compare generated vs existing apps.

## Usage Examples

- **Triage**: "Why is `payments` Degraded?" runs `triage_application` — app conditions, unhealthy nodes, warning events, then pod logs.
- **Drift**: "What has drifted in `prod`?" runs `review_drift` — lists OutOfSync apps and shows each diff.
- **Safe sync**: "Sync `web` safely" runs `safe_sync` — checks sync windows, dry-runs, then syncs and waits.
- **Rollback**: "Roll