mcp-read-only-argocd
This server provides read-only access to one or more Argo CD instances via MCP, allowing you to inspect and query GitOps deployments without making any changes. Authentication uses browser session cookies and multiple instances are supported.
Connections & Instance Info
list_connections– View all configured Argo CD instances (name, URL, description)get_version– Retrieve the Argo CD version of a specific instanceget_settings– Fetch the global settings of a specific Argo CD instance
Applications
list_applications– List all applications, optionally filtered by project names or label selectorsget_application– Get detailed info on a specific app (sync status, health, spec)get_application_resource_tree– View the full Kubernetes resource tree and relationships for an appget_application_managed_resources– List managed resources, filterable by API group, kind, namespace, or resource nameget_application_logs– Retrieve pod logs, with options for pod/container filtering, tail lines, and time window
Projects
list_projects– List all Argo CD projectsget_project– Get detailed project info including source repos, destinations, and roles
Clusters
list_clusters– List all registered Kubernetes clusters and their connection statusget_cluster– Get detailed info about a specific cluster by server URL
Repositories
list_repositories– List all configured Git/Helm repositories and their connection statusget_repository– Get detailed info about a specific repository by URL
Provides read-only access to Argo CD instances using browser session cookies, enabling listing applications, projects, clusters, repositories, and retrieving application details, resource trees, managed resources, and logs.
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., "@mcp-read-only-argocd List all applications in staging."
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.
MCP Read-Only Argo CD Server
A secure MCP (Model Context Protocol) server that provides read-only access to Argo CD instances using browser session cookies.
Default layout:
Config:
~/.config/lukleh/mcp-read-only-argocd/connections.yamlCredentials: stored in
connections.yamlCache:
~/.cache/lukleh/mcp-read-only-argocd/
Features
Read-only by design: only read operations are exposed
Session cookie authentication: uses your existing
argocd.tokenbrowser sessionMulti-instance support: connect to multiple Argo CD instances at once
Automatic cookie rotation: refreshed session cookies are persisted to
connections.yamlStale token recovery: a 401 response triggers a one-time Chrome cookie refresh and retry
Package-native runtime paths: no repository checkout required for normal use
Related MCP server: argocd-mcp
Why Session Cookies?
Unlike token-based setups, this server can reuse your existing browser session:
no extra API token management
uses your existing SSO/OIDC login
matches the permissions you already have in the UI
Prerequisites
Python 3.11 or higher
an Argo CD browser session cookie
an MCP client such as Claude Code or Codex
Quick Start
1. Install the Server
# Run the published package without cloning the repository
uvx mcp-read-only-argocd@latest --write-sample-config
# Or install it once and reuse the command directly
uv tool install mcp-read-only-argocd
mcp-read-only-argocd --write-sample-configWhen using uvx, prefer mcp-read-only-argocd@latest in user-facing docs and
MCP client configs. This avoids reusing a stale cached tool environment after a
new release is published.
The command above writes a starter config to ~/.config/lukleh/mcp-read-only-argocd/connections.yaml.
2. Confirm Runtime Paths
uvx mcp-read-only-argocd@latest --print-paths3. Edit the Connections File
Edit ~/.config/lukleh/mcp-read-only-argocd/connections.yaml:
- connection_name: staging
url: https://argocd.example.com
description: Staging Argo CD
session_token: your-session-token
- connection_name: production
url: https://argocd-prod.example.com
description: Production Argo CD
session_token: your-other-session-token4. Get Your argocd.token Session Cookie
Log in to your Argo CD web UI
Open browser developer tools
Go to Application/Storage -> Cookies
Copy the value of the
argocd.tokencookie
5. Store the Session Cookie
Put the cookie value in the session_token field for each connection in
~/.config/lukleh/mcp-read-only-argocd/connections.yaml. The server detects
changes to connections.yaml before tool calls, so editing this file does not
require an MCP restart.
If Argo CD rejects the active token with a 401 response, the server tries once to
load a fresh argocd.token from Chrome Profile 1 for the matching connection
domain. When that token differs from the active token, the failed request is
retried once. If the retry succeeds, the fresh token is written back to
connections.yaml.
6. Configure Your MCP Client
Claude Code
claude mcp add mcp-read-only-argocd \
--scope user \
-- uvx mcp-read-only-argocd@latestCodex
codex mcp add mcp-read-only-argocd \
-- uvx mcp-read-only-argocd@latest7. Restart and Test
Restart your MCP client and try a simple query such as:
List all applications in the staging Argo CD instance.Configuration
connections.yaml supports a list of Argo CD connections:
- connection_name: staging
url: https://argocd.example.com
description: Staging Argo CD instance
session_token: your-session-token
timeout: 30
verify_ssl: trueFields:
connection_name: unique identifier used in tool calls and token refreshesurl: Argo CD base URLdescription: optional human-readable descriptionsession_token: Argo CDargocd.tokenbrowser cookietimeout: optional request timeout in secondsverify_ssl: optional SSL verification toggle
Runtime path override environment variables:
MCP_READ_ONLY_ARGOCD_CONFIG_DIRMCP_READ_ONLY_ARGOCD_CACHE_DIR
Command Line Testing
# Show the resolved runtime paths
uvx mcp-read-only-argocd@latest --print-paths
# Write or refresh the default connections.yaml
uvx mcp-read-only-argocd@latest --write-sample-config
uvx mcp-read-only-argocd@latest --write-sample-config --overwrite
# Run the server with the default home-directory config
uvx mcp-read-only-argocd@latest
# Or point at a different runtime root
uvx mcp-read-only-argocd@latest --config-dir /path/to/config-dirMCP Tools
Core
list_connectionsget_versionget_settings
Applications
list_applicationsget_applicationget_application_resource_treeget_application_managed_resourcesget_application_logs
Projects
list_projectsget_project
Clusters
list_clustersget_cluster
Repositories
list_repositoriesget_repository
Local Development
If you want to work on the repository itself:
git clone https://github.com/lukleh/mcp-read-only-argocd.git
cd mcp-read-only-argocd
uv sync --extra dev
uv run pytest -q
uv run mcp-read-only-argocd --print-paths
uv run python smoke_test.py --print-pathsThe checked-in sample file remains available at connections.yaml.sample for documentation and review, but package users should prefer --write-sample-config.
License
MIT
Available Tools
14 toolsget_applicationB
Get detailed information about a specific application.
Args: connection_name: Name of the Argo CD connection name: Application name
Returns: JSON string with application details including sync status, health, and spec.
Inputs: connection_name (required), name (required). Returns: result
get_application_logsA
Get logs for an application's pods.
Args: connection_name: Name of the Argo CD connection name: Application name namespace: Optional namespace (defaults to application's namespace) pod_name: Optional specific pod name to get logs from container: Optional container name within the pod tail_lines: Number of lines from the end to return (e.g., 100) since_seconds: Return logs from the last N seconds
Returns: JSON string with log entries.
Inputs: connection_name (required), name (required), namespace, pod_name, +3 more. Returns: result
get_application_managed_resourcesA
Get managed resources for an application.
Args: connection_name: Name of the Argo CD connection name: Application name group: Optional API group to filter (e.g., "apps", "networking.k8s.io") kind: Optional resource kind to filter (e.g., "Deployment", "Service") namespace: Optional namespace to filter resource_name: Optional resource name to filter
Returns: JSON string with list of managed resources.
Inputs: connection_name (required), name (required), group, kind, +2 more. Returns: result
get_application_resource_treeB
Get the Kubernetes resource tree for an application.
Shows all resources created by the application and their relationships.
Args: connection_name: Name of the Argo CD connection name: Application name
Returns: JSON string with resource tree including nodes and their parent references.
Inputs: connection_name (required), name (required). Returns: result
get_clusterB
Get detailed information about a specific cluster.
Args: connection_name: Name of the Argo CD connection server: Cluster server URL (e.g., "https://kubernetes.default.svc")
Returns: JSON string with cluster details including connection info and namespaces.
Inputs: connection_name (required), server (required). Returns: result
get_projectA
Get detailed information about a specific project.
Args: connection_name: Name of the Argo CD connection name: Project name
Returns: JSON string with project details including source repos, destinations, and roles.
Inputs: connection_name (required), name (required). Returns: result
get_repositoryA
Get detailed information about a specific repository.
Args: connection_name: Name of the Argo CD connection repo: Repository URL (e.g., "https://github.com/org/repo")
Returns: JSON string with repository details including connection status and type.
Inputs: connection_name (required), repo (required). Returns: result
get_settingsC
Get Argo CD settings.
Args: connection_name: Name of the Argo CD connection
Returns: JSON string with Argo CD settings.
Inputs: connection_name (required). Returns: result
get_versionA
Get Argo CD version information.
Args: connection_name: Name of the Argo CD connection to check
Returns: JSON string with version information.
Inputs: connection_name (required). Returns: result
list_applicationsA
List all applications in Argo CD.
Args: connection_name: Name of the Argo CD connection projects: Optional list of project names to filter by selector: Optional label selector to filter applications (e.g., "app=myapp")
Returns: JSON string with list of applications.
Inputs: connection_name (required), projects, selector. Returns: result
list_clustersA
List all clusters registered in Argo CD.
Args: connection_name: Name of the Argo CD connection
Returns: JSON string with list of clusters including server URLs and connection status.
Inputs: connection_name (required). Returns: result
list_connectionsA
List all available Argo CD connections with their configuration details.
Returns: JSON string with connection details including name, url, and description.
Inputs: no named parameters. Returns: result
list_projectsB
List all projects in Argo CD.
Projects define the scope of resources an application can deploy.
Args: connection_name: Name of the Argo CD connection
Returns: JSON string with list of projects.
Inputs: connection_name (required). Returns: result
list_repositoriesB
List all repositories configured in Argo CD.
Args: connection_name: Name of the Argo CD connection
Returns: JSON string with list of repositories including URLs and connection status.
Inputs: connection_name (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct Argo CD resource or aspect (e.g., application details, logs, managed resources). There is no overlap in purpose, and descriptions clearly differentiate them.
All tools follow the verb_noun pattern with snake_case (e.g., get_application, list_applications). Naming is consistent and predictable throughout.
With 14 tools covering the main read-only operations for Argo CD (applications, clusters, projects, repositories, settings), the count is well-scoped and each tool earns its place.
The tool set provides comprehensive read-only coverage: listing and getting details for all major resources, plus application logs, managed resources, and resource tree. No obvious gaps for a read-only interface.
Maintenance
Related MCP Connectors
MCP server for Appcircle mobile CI/CD platform.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
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- AlicenseAqualityBmaintenanceRead-only MCP server for safe Kubernetes inspection, diagnosis, and debugging. Supports Kubernetes core, Helm, Argo Workflows, and Argo CD.2133 npm5MIT
- AlicenseBqualityCmaintenanceMCP server for Argo CD that provides multi-environment profiles, SSO or API key authentication, application search with cache, and REST API tools from the bundled OpenAPI catalog.26MIT