Skip to main content
Glama
@godrix/argocd-mcp

@godrix/argocd-mcp

by godrix

@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); auto re-login on 401 when using CLI/SSO; 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: argocd-mcp

Prerequisites

Requirement

SSO login

API key only

Node.js 20+

Yes

Yes

Argo CD CLI (argocd)

Yes

No

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+

Platform

Install

macOS

nodejs.org or brew install node@20

Linux (Debian/Ubuntu)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - → sudo apt install -y nodejs

Linux (Fedora/RHEL)

sudo dnf install nodejs or nvm

Windows

nodejs.org or winget install OpenJS.NodeJS.LTS

node --version   # v20+

Argo CD CLI (for SSO)

Platform

Install

macOS

brew install argocd

Linux (amd64)

curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 && sudo chmod +x /usr/local/bin/argocd

Linux (arm64)

Use argocd-linux-arm64 in the URL above

Windows (Scoop)

scoop install argocd

Windows (Chocolatey)

choco install argocd-cli

Windows (manual)

Latest release → argocd-windows-amd64.exe → add to PATH

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

Variable

Required

Default

Description

ARGOCD_URL

Single mode

—

Argo CD base URL

ARGOCD_DEFAULT_PROFILE

Multi mode

—

Default profile name (must be in ARGOCD_PROFILES)

ARGOCD_PROFILES

Multi mode

—

Comma-separated profile names

ARGOCD_URL_PROFILES

Multi mode

—

Comma-separated URLs (same order as profiles)

ARGOCD_API_KEY

No

—

Bearer token (default profile or single instance)

ARGOCD_API_KEY_<PROFILE>

No

—

Per-profile API key (e.g. ARGOCD_API_KEY_QA)

ARGOCD_API_KEYS

No

—

Comma-separated keys (same order as ARGOCD_PROFILES)

ARGOCD_TOKEN / ARGOCD_TOKEN_<PROFILE>

No

—

Aliases for API key vars

ARGOCD_READ_ONLY

No

true

Block sync and other mutations

ARGOCD_ALLOW_REFRESH

No

true

Allow refresh-application

ARGOCD_AUTO_SSO_RELOGIN

No

true

On 401/403 with CLI/SSO auth, run argocd login --sso (opens browser) and retry once

ARGOCD_SKIP_TEST_TLS

No

true

Pass --skip-test-tls to argocd login (faster when SSO session expired)

ARGOCD_APP_CACHE_ENABLED

No

true

In-memory application name cache

ARGOCD_APP_CACHE_TTL_SECONDS

No

300

Cache TTL

ARGOCD_PRIORITY_APPS

No

—

Comma-separated bookmark app names

ARGOCD_PRIORITY_APPS_<PROFILE>

No

—

Per-profile priority apps

ARGOCD_GRPC_WEB

No

true

Pass --grpc-web to argocd login

ARGOCD_CONFIG

No

~/.config/argocd/config

Path to argocd CLI config

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

Authentication

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

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:

  • CLI/SSO auth (default interactive flow): with ARGOCD_AUTO_SSO_RELOGIN=true, the next API call triggers argocd login --sso (browser opens) and retries automatically. You can also call argocd_login manually.

  • API key auth: rotate the token or use argocd_set_api_key.

Set ARGOCD_AUTO_SSO_RELOGIN=false in headless/CI environments without a browser.

How the agent knows the token expired:

Signal

What it means

argocd_auth_status

tokenValid: false + recommendedAction (SSO → argocd_login; API key → rotate key)

Any API tool returns 401/403

SSO: auto re-login may run; otherwise error tells agent to call argocd_login (not API keys)

list-argocd-profiles with validateTokens: true

Live probe without calling other tools

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

MCP tools

Core

Tool

Description

list-argocd-profiles

Profiles, URLs, auth status

argocd_login

SSO or username/password via CLI

argocd_set_api_key

API token in memory for this session

argocd_auth_status

Auth status per profile

get-argocd-settings

Public settings

get-argocd-userinfo

User + groups

search-argocd-endpoints

Search swagger catalog

describe-argocd-endpoint

Endpoint parameters

call-argocd-api

Generic REST call

Applications

Tool

Description

list-applications

List/filter; nameContains for substring via cache

search-applications

LIKE search on cached names

refresh-application-cache

Force cache refresh

application-cache-status

Cache TTL / count per profile

list-priority-applications

Apps from ARGOCD_PRIORITY_APPS

get-application

Full status

get-application-diff

Server-side diff

get-application-manifests

Rendered manifests

refresh-application

Refresh from Git

get-application-resource-tree

Resource tree

get-application-pod-logs

Pod logs

diagnose-application

Status + tree + events + pod logs

view-application-observability

MCP App — painel interativo (health, sync, Git, conditions, unhealthy)

refresh-application-observability

Recarrega dados do widget (visível só para a UI)

sync-application

Trigger sync (ARGOCD_READ_ONLY=false)

terminate-application-operation

Cancel operation

Infra

Tool

Description

list-projects

Argo CD AppProjects

Resources

URI

Description

argocd://profiles

Profiles + auth

argocd://priority-apps

Priority app names

argocd://settings/{profile}

Public settings (cached)

argocd://application-index/{profile}

Cached application names

Prompts

Prompt

Description

daily-argocd-healthcheck

Priority + degraded + outofsync sweep

investigate-outofsync

Diff + recommendation

safe-sync-application

RBAC + diff before sync

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.

  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

CLI

Product

argo

Argo Workflows

argocd

Argo CD (this MCP)

License

MIT

Available Tools

26 tools
application-cache-statusA

Show application cache status per profile (enabled, TTL, count, expiry).

Inputs: no named parameters.

argocd_auth_statusA

Show authentication status for all configured Argo CD profiles. Probes the API to detect expired or revoked tokens and returns recommendedAction (e.g. run argocd_login again).

Inputs: no named parameters.

argocd_loginA

Authenticate to Argo CD for a profile. Default: SSO via argocd CLI (opens browser immediately). When SSO expires, call this directly — do not try API keys first. For API tokens without CLI login, use argocd_set_api_key or ARGOCD_API_KEY env vars.

Inputs: sso, grpcWeb, profile, ssoPort, +4 more.

argocd_set_api_keyA

Set an Argo CD API key (Bearer token) in memory for the current MCP session. Use when you have a token from the Argo CD UI (User Settings → API tokens) or argocd account generate-token. Env vars (ARGOCD_API_KEY) take precedence on server restart.

Inputs: apiKey (required), profile.

call-argocd-apiC

Execute a read-only Argo CD REST API call (GET). Mutations are blocked while ARGOCD_READ_ONLY=true.

Inputs: path (required), method (required), body, profile, +2 more.

describe-argocd-endpointB

Get full parameter documentation for an Argo CD API endpoint from swagger.

Inputs: path, method, operationId.

diagnose-applicationA

Composite troubleshooting: application status + resource tree + events + logs from unhealthy pods.

Inputs: name (required), profile, tailLines, maxPodLogs.

get-applicationA

Get detailed status of a single Argo CD application (sync, health, conditions, source).

Inputs: name (required), profile.

get-application-diffA

Server-side dry-run diff for an application (what would change on sync).

Inputs: name (required), profile, project, appNamespace.

get-application-manifestsB

Get rendered manifests for an application (optionally at a specific revision).

Inputs: name (required), noCache, profile, project, +1 more.

get-application-pod-logsA

Get pod logs for an application (buffered tail, no streaming). Specify podName or use filters.

Inputs: name (required), filter, podName, profile, +4 more.

get-application-resource-treeB

Get the resource tree for an application (pods, services, deployments, health per node).

Inputs: name (required), profile.

get-argocd-settingsA

Get public Argo CD settings for an environment profile (URL, OIDC config, UI banners). Does not require authentication.

Inputs: server, profile.

get-argocd-userinfoA

Get the authenticated user for an environment profile (username, Azure groups, issuer).

Inputs: profile.

list-applicationsA

List Argo CD applications with optional filters. Priority apps from env (ARGOCD_PRIORITY_APPS) appear first with isPriority=true.

Inputs: name, repo, limit, profile, +9 more.

list-argocd-profilesA

List configured Argo CD environment profiles (qa, stg, prod, etc.) with URLs and authentication status.

Inputs: validateTokens.

list-priority-applicationsA

List MCP priority/bookmark applications configured in env (ARGOCD_PRIORITY_APPS). Fetches live status for each name. Argo CD UI favorites are browser-only and cannot be read via API.

Inputs: profile, namesOnly.

list-projectsA

List Argo CD AppProjects with description, allowed source repos, and destinations.

Inputs: name, profile, namesOnly.

refresh-applicationB

Refresh an application (reconcile from Git). Use mode=hard to invalidate cache. Allowed when ARGOCD_ALLOW_REFRESH=true (default).

Inputs: name (required), mode, profile.

refresh-application-cacheA

Force refresh the in-memory application name cache for a profile. Useful after creating/deleting applications.

Inputs: profile.

refresh-application-observabilityAtualizar observabilidadeA
Read-only

Recarrega dados de observabilidade para o widget. Chamado pela UI, não pelo modelo.

Inputs: name (required), profile.

search-applicationsA

Search Argo CD applications by substring (LIKE) using an in-memory cache. Matches name, project, repo, path and namespace. The Argo CD API only supports exact name match — use this tool for partial search (e.g. query='adherence').

Inputs: query (required), limit, profile, project, +4 more.

search-argocd-endpointsA

Search Argo CD REST API endpoints from the bundled swagger catalog. Use before call-argocd-api.

Inputs: tag, query.

sync-applicationC

Sync application to target state. Blocked while ARGOCD_READ_ONLY=true.

Inputs: name (required), force, prune, dryRun, +2 more.

terminate-application-operationA

Terminate running sync/operation. Blocked while ARGOCD_READ_ONLY=true.

Inputs: name (required), profile.

view-application-observabilityObservabilidade da applicationA
Read-only

Abre um painel interativo com health, sync, Git, conditions e recursos unhealthy de uma application Argo CD. Em hosts sem MCP App, retorna JSON e resumo em texto.

Inputs: name (required), profile.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools map to clearly distinct resources and actions, such as get-application, sync-application, and list-projects. A few pairs like view-application-observability vs diagnose-application or list-applications vs search-applications could be confused, but the descriptions provide enough distinction.

    Naming Consistency3/5

    The majority of tools follow a readable verb-noun kebab-case pattern like get-application and sync-application. However, several tools use snake_case (argocd_login, argocd_set_api_key, argocd_auth_status) and a few use noun-first names like application-cache-status, making the overall naming style inconsistent.

    Tool Count2/5

    With 26 tools, the server exceeds the 25-tool threshold and feels heavier than necessary. Several narrow helpers such as application-cache-status, refresh-application-cache, and observability-specific tools could be consolidated without losing core functionality.

    Completeness3/5

    The tool set covers Argo CD inspection, sync, refresh, auth, project listing, and troubleshooting well. However, there are notable lifecycle gaps: no create/update/delete application or project operations, and call-argocd-api is restricted to read-only GET calls.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP (Model Context Protocol) server that integrates with the ArgoCD API, enabling AI assistants and large language models to manage ArgoCD applications and resources through natural language interactions.
      10
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A secure MCP server providing read-only access to Argo CD instances using browser session cookies, enabling querying of applications, projects, clusters, and repositories.
      14
      30 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible clients to inspect Argo CD applications, check sync and health status, list resources, review events, refresh applications, and optionally trigger sync operations.
      MIT