Skip to main content
Glama
mcp-read-only-argocd

mcp-read-only-argocd

by lukleh

MCP Read-Only Argo CD Server

Tests License: MIT Python 3.11+

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

  • Credentials: stored in connections.yaml

  • Cache: ~/.cache/lukleh/mcp-read-only-argocd/

Features

  • Read-only by design: only read operations are exposed

  • Session cookie authentication: uses your existing argocd.token browser session

  • Multi-instance support: connect to multiple Argo CD instances at once

  • Automatic cookie rotation: refreshed session cookies are persisted to connections.yaml

  • Stale 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

  • uv

  • 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-config

When 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-paths

3. 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-token

4. Get Your argocd.token Session Cookie

  1. Log in to your Argo CD web UI

  2. Open browser developer tools

  3. Go to Application/Storage -> Cookies

  4. Copy the value of the argocd.token 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@latest

Codex

codex mcp add mcp-read-only-argocd \
  -- uvx mcp-read-only-argocd@latest

7. 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: true

Fields:

  • connection_name: unique identifier used in tool calls and token refreshes

  • url: Argo CD base URL

  • description: optional human-readable description

  • session_token: Argo CD argocd.token browser cookie

  • timeout: optional request timeout in seconds

  • verify_ssl: optional SSL verification toggle

Runtime path override environment variables:

  • MCP_READ_ONLY_ARGOCD_CONFIG_DIR

  • MCP_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-dir

MCP Tools

Core

  • list_connections

  • get_version

  • get_settings

Applications

  • list_applications

  • get_application

  • get_application_resource_tree

  • get_application_managed_resources

  • get_application_logs

Projects

  • list_projects

  • get_project

Clusters

  • list_clusters

  • get_cluster

Repositories

  • list_repositories

  • get_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-paths

The 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 tools
get_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

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow the verb_noun pattern with snake_case (e.g., get_application, list_applications). Naming is consistent and predictable throughout.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    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
      B
      quality
      C
      maintenance
      MCP 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.
      26
      MIT