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

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

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@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