MCP Argocd

mcp-argocd

mcp-argocd is a Model Context Protocol (MCP) 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. Runs in one of two modes: with writes, or locked read-only (MCP_READ_ONLY=true) so the 9 write tools are never offered to the model.

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 4.x, httpx, and Pydantic.

Install: uvx mcp-argocd | PyPI | MCP Registry | Changelog

uvx mcp-argocd                          # with writes

MCP_READ_ONLY=true uvx mcp-argocd # locked read-only: write tools are not listed

1-Click Installation

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).

Manual Setup Guides (Click to expand)

Prerequisite: Install uv first. Install uv.

Claude Code

# with writes

claude mcp add argocd -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN= -- uvx mcp-argocd

locked read-only

claude mcp add argocd -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN= -- uvx mcp-argocd

Windsurf & IntelliJ

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

Remove MCP_READ_ONLY to allow writes.

{

"mcpServers": { "argocd": { "command": "uvx", "args": ["mcp-argocd"], "env": { "ARGOCD_URL": "https://argocd.example.com", "ARGOCD_TOKEN": " ", "MCP_READ_ONLY": "true" } } } }

Gemini CLI

The repo ships gemini-extension.json; install it with the Gemini CLI extension flow, or add it directly:

# with writes

gemini mcp add -s user -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN= argocd uvx mcp-argocd

locked read-only

gemini mcp add -s user -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN= argocd uvx mcp-argocd

VS Code

Add to .vscode/mcp.json. Remove MCP_READ_ONLY to allow writes.

{

"servers": { "argocd": { "type": "stdio", "command": "uvx", "args": ["mcp-argocd"], "env": { "ARGOCD_URL": "https://argocd.example.com", "ARGOCD_TOKEN": " ", "MCP_READ_ONLY": "true" } } } }

Codex

# with writes

codex mcp add argocd --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN= -- uvx mcp-argocd

locked read-only

codex mcp add argocd --env MCP_READ_ONLY=true --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN= -- uvx mcp-argocd

pip / uv

uvx mcp-argocd            # run without installing

pip install mcp-argocd # or install into an environment

Drop MCP_READ_ONLY to allow writes. On a shared or hosted server put it in the deployer's env, not the client config.

Configuration

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

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.

Error results

Expected failures — a missing app (404), a denied permission (403), a write that reaches the read-only guard — return a tool result with isError: true rather than a success envelope. (In locked read-only mode the write tools are hidden, so calling one returns an Unknown tool error; the envelope below is the guard's own response, returned only when a client reaches a write tool anyway.) The body is a JSON object {"error", "status_code"?, "body"?, "hint"?}, where hint names a corrective action when one applies. The body is the result's pretty-printed text content; the result carries no structuredContent, because a strict MCP client (the TypeScript SDK) validates structuredContent against the tool's outputSchema even when isError is true and would reject the error otherwise. Unexpected bugs are also isError: true but carry TypeName: message text and a logged traceback. Successful results carry the same JSON object as structuredContent alongside the pretty-printed text, so a client may read either. Tools advertise no outputSchema: payloads pass upstream fields through untyped, and a typed schema is opt-in per tool via output_schema=.

Tools (37)

Full tool reference (Click to expand)

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.

Resources (7)

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

• `resourc