@godrix/argocd-mcp
Allows interaction with Argo CD, enabling AI agents to manage applications (list, search, diff, manifests, diagnose, sync), authenticate via SSO or API keys, and call Argo CD API endpoints across multiple environments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@godrix/argocd-mcp list applications in production"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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_URLorARGOCD_PROFILES+ARGOCD_URL_PROFILESSSO login —
argocd_loginviaargocdCLI (Azure OIDC); auto re-login on 401 when using CLI/SSO; or API key via env /argocd_set_api_keyApplication 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-apiover full swagger catalogResources & prompts — profiles, priority apps, settings, health-check workflows
Read-only by default —
ARGOCD_READ_ONLY=trueblocks mutations
Related MCP server: argocd-mcp
Prerequisites
Requirement | SSO login | API key only |
Node.js 20+ | Yes | Yes |
Argo CD CLI ( | Yes | No |
Install
argocd(Argo CD), notargo(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 |
Linux (Debian/Ubuntu) |
|
Linux (Fedora/RHEL) |
|
Windows | nodejs.org or |
node --version # v20+Argo CD CLI (for SSO)
Platform | Install |
macOS |
|
Linux (amd64) |
|
Linux (arm64) | Use |
Windows (Scoop) |
|
Windows (Chocolatey) |
|
Windows (manual) | Latest release → |
Docs: Argo CD CLI installation
argocd version --clientFrom source
git clone <repo-url> mcp-argocd
cd mcp-argocd
npm install
npm run build
cp .env.example .env # edit URLs / keysPoint 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:
Clone the repo and install:
npm install && npm run buildnpm run pack:mcpb— bundle withmanifest.json,build/,swagger.txt, andnode_modulesSmaller bundle:
npm run pack:mcpb:slimInstall the
.mcpbin 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.ioMultiple 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.ioOptional per profile: ARGOCD_PROFILE_<NAME>_CONTEXT, _LABEL, _URL.
Environment variables
Variable | Required | Default | Description |
| Single mode | — | Argo CD base URL |
| Multi mode | — | Default profile name (must be in |
| Multi mode | — | Comma-separated profile names |
| Multi mode | — | Comma-separated URLs (same order as profiles) |
| No | — | Bearer token (default profile or single instance) |
| No | — | Per-profile API key (e.g. |
| No | — | Comma-separated keys (same order as |
| No | — | Aliases for API key vars |
| No |
| Block sync and other mutations |
| No |
| Allow |
| No |
| On 401/403 with CLI/SSO auth, run |
| No |
| Pass |
| No |
| In-memory application name cache |
| No |
| Cache TTL |
| No | — | Comma-separated bookmark app names |
| No | — | Per-profile priority apps |
| No |
| Pass |
| No |
| 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.
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-prodRuntime (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: truesequenceDiagram
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 successfulTools:
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 qaWhen the JWT expires:
CLI/SSO auth (default interactive flow): with
ARGOCD_AUTO_SSO_RELOGIN=true, the next API call triggersargocd login --sso(browser opens) and retries automatically. You can also callargocd_loginmanually.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 |
|
|
Any API tool returns 401/403 | SSO: auto re-login may run; otherwise error tells agent to call |
| 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 |
| Profiles, URLs, auth status |
| SSO or username/password via CLI |
| API token in memory for this session |
| Auth status per profile |
| Public settings |
| User + groups |
| Search swagger catalog |
| Endpoint parameters |
| Generic REST call |
Applications
Tool | Description |
| List/filter; |
| LIKE search on cached names |
| Force cache refresh |
| Cache TTL / count per profile |
| Apps from |
| Full status |
| Server-side diff |
| Rendered manifests |
| Refresh from Git |
| Resource tree |
| Pod logs |
| Status + tree + events + pod logs |
| MCP App — painel interativo (health, sync, Git, conditions, unhealthy) |
| Recarrega dados do widget (visível só para a UI) |
| Trigger sync ( |
| Cancel operation |
Infra
Tool | Description |
| Argo CD AppProjects |
Resources
URI | Description |
| Profiles + auth |
| Priority app names |
| Public settings (cached) |
| Cached application names |
Prompts
Prompt | Description |
| Priority + degraded + outofsync sweep |
| Diff + recommendation |
| 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 (
openLinkpara a URL da application)Botão Atualizar (chama
refresh-application-observabilityviacallServerTool)
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
list-argocd-profiles— check environments and authargocd_login(SSO) or setARGOCD_API_KEY/argocd_set_api_keysearch-applicationsorlist-applicationsfor discoverydiagnose-application/get-application-difffor troubleshootingcall-argocd-apifor 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 bundleargo vs argocd
CLI | Product |
| Argo Workflows |
| Argo CD (this MCP) |
License
MIT
Available Tools
26 toolsapplication-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 observabilidadeARead-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 applicationARead-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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
The official MCP Server from Mia-Platform to interact with Mia-Platform Console
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.1012MIT

argocd-mcpofficial
AlicenseCqualityCmaintenanceAn implementation of Model Context Protocol (MCP) server for Argo CD.1420,533 npm606Apache 2.0- AlicenseAqualityCmaintenanceA secure MCP server providing read-only access to Argo CD instances using browser session cookies, enabling querying of applications, projects, clusters, and repositories.1430 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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