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
• Rotated session state: ~/.local/state/lukleh/mcp-read-only-argocd/session_tokens.json
• 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 local state
• 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 persists rotated session cookies to ~/.local/state/lukleh/mcp-read-only-argocd/session_tokens.json, keyed by connection_name. The server detects changes to connections.yaml before tool calls, so editing this file does not require an MCP restart. If both connections.yaml and the state file contain a token for the same connection, the persisted state file wins until you update or remove it.

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 rotated session state
• 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_STATE_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