@godrix/argocd-mcp

MCP Server for Argo CD: multi-environment profiles (qa/stg/prod), SSO or API-key auth, application search cache, and REST tools from the bundled OpenAPI catalog.

Features

• Multi-environment profiles — single ARGOCD_URL or ARGOCD_PROFILES + ARGOCD_URL_PROFILES

• SSO login — argocd_login via argocd CLI (Azure OIDC); or API key via env / argocd_set_api_key

• Application tools — list, search (LIKE cache), diff, manifests, diagnose, sync (opt-in)

• MCP App — observabilidade — widget inline com health, sync, Git, conditions e link para o Argo CD UI

• Generic API — search-argocd-endpoints + call-argocd-api over full swagger catalog

• Resources & prompts — profiles, priority apps, settings, health-check workflows

• Read-only by default — ARGOCD_READ_ONLY=true blocks mutations

Related MCP server: Rancher MCP Server

Prerequisites

Install argocd (Argo CD), not argo (Argo Workflows). See argo vs argocd.

Quick start (Cursor / npx)

No clone required after publish:

{
  "mcpServers": {
    "argocd": {
      "command": "npx",
      "args": ["-y", "@godrix/argocd-mcp"],
      "env": {
        "ARGOCD_URL": "https://argocd-qa.example.io",
        "ARGOCD_API_KEY": "eyJhbGciOi...",
        "ARGOCD_READ_ONLY": "true"
      }
    }
  }
}

Multi-environment:

{
  "mcpServers": {
    "argocd": {
      "command": "npx",
      "args": ["-y", "@godrix/argocd-mcp"],
      "env": {
        "ARGOCD_DEFAULT_PROFILE": "qa",
        "ARGOCD_PROFILES": "qa,stg,prod",
        "ARGOCD_URL_PROFILES": "https://qa.example.io,https://stg.example.io,https://prod.example.io",
        "ARGOCD_READ_ONLY": "true"
      }
    }
  }
}

Restart Cursor after saving. Then ask the agent to run argocd_auth_status or argocd_login.

Installation

Node.js 20+

node --version   # v20+

Argo CD CLI (for SSO)

Docs: Argo CD CLI installation

argocd version --client

From source

git clone <repo-url> mcp-argocd
cd mcp-argocd
npm install
npm run build
cp .env.example .env   # edit URLs / keys

Point Cursor at the build output:

{
  "mcpServers": {
    "argocd": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-argocd/build/server.js"],
      "env": {
        "ARGOCD_URL": "https://argocd-qa.example.io",
        "ARGOCD_READ_ONLY": "true"
      }
    }
  }
}

MCPB install (Claude Desktop / local bundle)

Alternative to npx for clients that support .mcpb files:

1. Clone the repo and install: npm install && npm run build

2. npm run pack:mcpb — bundle with manifest.json, build/, swagger.txt, and node_modules

3. Smaller bundle: npm run pack:mcpb:slim

4. Install the .mcpb in your client and fill in URL / API key / profiles in the UI

The bundle form maps to the same env vars (ARGOCD_URL, ARGOCD_API_KEY, ARGOCD_PROFILES, etc.). SSO still requires the argocd CLI on PATH and a desktop browser.

CI publishes the .mcpb to GitHub Releases on each version bump (see .github/workflows/release.yml).

Configuration

Environment profiles

Two mutually exclusive modes:

Single instance — only ARGOCD_URL (implicit profile default):

ARGOCD_URL=https://argocd-qa.example.io

Multiple environments — all three required (do not set ARGOCD_URL):

ARGOCD_DEFAULT_PROFILE=qa
ARGOCD_PROFILES=qa,stg,prod
ARGOCD_URL_PROFILES=https://qa.example.io,https://stg.example.io,https://prod.example.io

Optional per profile: ARGOCD_PROFILE_<NAME>_CONTEXT, _LABEL, _URL.

Environment variables

Legacy: ARGOCD_PROFILES_FILE loads JSON; env vars override file entries.

Authentication

Use one method per profile: API key or CLI login.

Option A — API key (recommended for MCP / CI)

Token from Argo CD UI (User Settings → API tokens) or argocd account generate-token.

# single instance
ARGOCD_API_KEY=eyJhbGciOi...

# multi-env
ARGOCD_API_KEY_QA=eyJ...
ARGOCD_API_KEYS=key-qa,key-stg,key-prod

Runtime (current MCP session only):

argocd_set_api_key { "profile": "qa", "apiKey": "eyJ..." }

Priority: memory → env per profile → ARGOCD_API_KEYS → ARGOCD_API_KEY → CLI config.

Option B — SSO login (interactive)

No USE_SSO env var — SSO is the default for argocd_login.

1. Configure profiles (ARGOCD_URL or multi-env vars)
2. Agent calls argocd_login { "profile": "qa" }
3. MCP runs: argocd login <host> --sso --name <context> --grpc-web
4. Browser opens → Microsoft/Azure OIDC
5. JWT saved to ~/.config/argocd/config  (Windows: %USERPROFILE%\.config\argocd\config)
6. MCP reads token for subsequent API calls
7. Verify: argocd_auth_status → authenticated: true

sequenceDiagram
    participant User
    participant Cursor
    participant MCP as argocd-mcp
    participant CLI as argocd CLI
    participant Browser
    participant IdP as Azure OIDC

    User->>Cursor: Login Argo CD QA
    Cursor->>MCP: argocd_login profile=qa
    MCP->>CLI: argocd login --sso --grpc-web
    CLI->>Browser: Open SSO
    User->>IdP: Authenticate
    IdP->>CLI: OAuth callback
    CLI->>CLI: Save JWT
    MCP-->>Cursor: SSO login successful

Tools:

argocd_login { "profile": "qa" }

argocd_login { "profile": "qa", "sso": false, "username": "admin", "password": "..." }

Manual (terminal) — MCP reuses the same config:

argocd login argocd-qa.example.io --sso --grpc-web --name qa

When the JWT expires, run argocd_login again or switch to an API key.

How the agent knows the token expired:

tokenPresent: true only means a token exists in env/CLI config — use argocd_auth_status to confirm it still works.

MCP tools

Core

Applications

Infra

Resources

Prompts

MCP App — Observabilidade

A tool view-application-observability abre um widget inline (quando o host suporta MCP Apps) com o estado de uma application:

• Badges de health e sync

• Metadados Git (repo, path, revisions)

• Conditions reportadas pelo Argo CD

• Lista de recursos unhealthy (resource tree, sem pod logs)

• Botão Abrir no Argo CD (openLink para a URL da application)

• Botão Atualizar (chama refresh-application-observability via callServerTool)

Em hosts sem suporte a MCP App (ex. alguns modos do Cursor), a mesma tool retorna structuredContent JSON + resumo em texto — o agente continua operacional.

view-application-observability(profile: "qa", name: "my-service")

Widget visível em clientes com @modelcontextprotocol/ext-apps (ex. Claude com connectors). No Cursor depende da versão/feature de MCP Apps.

Recommended workflow

1. list-argocd-profiles — check environments and auth

2. argocd_login (SSO) or set ARGOCD_API_KEY / argocd_set_api_key

3. search-applications or list-applications for discovery

4. diagnose-application / get-application-diff for troubleshooting

5. call-argocd-api for anything else in swagger

Development

npm install
npm run build
npm test
npm run dev:mcp          # MCP Inspector
npm run pack:mcpb        # local .mcpb bundle
npm run pack:mcpb:slim   # production-sized bundle

argo vs argocd

License

MIT