Configuration

Complete configuration guide for the ArgoCD MCP Server including environment variables, Docker setup, MCP client configuration, and access control.

---

📋 Prerequisites

Requirement	Description
ArgoCD Server	Running ArgoCD instance (v2.x)
Authentication	ArgoCD API token
Git Credentials	HTTPS token or SSH key for repository onboarding
Python 3.12+	For local installation

Getting ArgoCD Token

Use the provided Python script to fetch your ArgoCD authentication token:

# Navigate to the scripts directory
cd argocd_mcp_server/scripts

# Set environment variables
export ARGOCD_SERVER="https://localhost:8080"
export ARGOCD_USERNAME="admin"
export ARGOCD_PASSWORD="your-password"
export ARGOCD_VERIFY_TLS="false"  # For self-signed certs

# Get export command for direct use
python fetch_argocd_token.py --output env
# Output: export ARGOCD_AUTH_TOKEN='eyJhbGc...'

---

📦 Installation Options

Option 1: Docker (Recommended)

# Pull the latest image
docker pull talkopsai/argocd-mcp-server:latest

# Run with default configuration (read-only mode)
docker run --rm -it \
  -p 8770:8770 \
  -e ARGOCD_SERVER_URL="https://argocd.example.com" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e MCP_PORT=8770 \
  -e MCP_PATH="/mcp" \
  talkopsai/argocd-mcp-server:latest

# Run with write access enabled (includes Git credentials for repo onboarding)
docker run --rm -it \
  -p 8770:8770 \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e MCP_PORT=8770 \
  -e MCP_PATH="/mcp" \
  -e ARGOCD_INSECURE="true" \
  -e GIT_PASSWORD="your-github-pat" \
  -e MCP_ALLOW_WRITE="true" \
  -e GIT_USERNAME="your-github-username" \
  talkopsai/argocd-mcp-server:latest

For ArgoCD on Host Machine (Port-Forwarded)

If your ArgoCD is port-forwarded (kubectl port-forward svc/argocd-server -n argocd 8080:443):

docker run --rm -it \
  -p 8770:8770 \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e MCP_PORT=8770 \
  -e MCP_PATH="/mcp" \
  -e ARGOCD_INSECURE="true" \
  -e MCP_ALLOW_WRITE="true" \
  talkopsai/argocd-mcp-server:latest

note

host.docker.internal is a special DNS name that resolves to your host machine from inside the Docker container (Mac/Windows only).

Option 2: Using uv

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone git@github.com:talkops-ai/talkops-mcp.git
cd talkops-mcp/src/argocd-mcp-server

# Create virtual environment and install
uv venv --python=3.12
source .venv/bin/activate

uv pip install -e .
uv run argocd-mcp-server

Option 3: Using pip

git clone git@github.com:talkops-ai/talkops-mcp.git
cd talkops-mcp/src/argocd-mcp-server

python -m venv .venv
source .venv/bin/activate

pip install -e .

---

⚙️ Environment Variables

Server Configuration

Variable	Default	Description
MCP_SERVER_NAME	argocd-mcp-server	Server name identifier
MCP_SERVER_VERSION	0.1.0	Server version string
MCP_TRANSPORT	streamable-http	Transport mode: streamable-http or stdio
MCP_HOST	0.0.0.0	Host address for streamable-http server
MCP_PORT	8770	Port for streamable-http server
MCP_PATH	/mcp	Endpoint path
MCP_ALLOW_WRITE	false	Enable write operations (see below)
MCP_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR

ArgoCD Configuration

Variable	Default	Description
ARGOCD_SERVER_URL	(required)	ArgoCD server URL
ARGOCD_AUTH_TOKEN	(required)	ArgoCD API authentication token
ARGOCD_INSECURE	false	Skip TLS verification
ARGOCD_TIMEOUT	300	Timeout in seconds for API operations

Git Repository Credentials

Variable	Default	Description
GIT_USERNAME	""	Git username (optional for token-only auth)
GIT_PASSWORD	(required for HTTPS)	GitHub personal access token
SSH_PRIVATE_KEY_PATH	~/.ssh/id_rsa	Path to SSH private key

---

🔐 Write Access Control

The MCP_ALLOW_WRITE environment variable controls whether mutating operations are allowed.

When MCP_ALLOW_WRITE=false (Default - Read-Only Mode) 🛡️

Operation	Status
List applications, repositories, projects	✅ Allowed
Get status, logs, events, metrics	✅ Allowed
Validate configs, preview diffs	✅ Allowed
Sync with dry_run=true (preview only)	✅ Allowed
Create applications, projects, repos	❌ Blocked
Update application configs	❌ Blocked
Delete applications, projects, repos	❌ Blocked
Sync (deploy) applications	❌ Blocked
Rollback deployments	❌ Blocked

Error message when blocked:

ArgoCDOperationError: ArgoCD [operation] is not allowed.
This MCP server is configured for read-only operations.
To enable write operations, set environment variable: MCP_ALLOW_WRITE=true

When MCP_ALLOW_WRITE=true (Write Mode) ✅

All operations are enabled:

• ✅ All read-only operations
• ✅ Create applications, projects, repositories
• ✅ Update/modify application configurations
• ✅ Delete applications, projects, repositories
• ✅ Sync and deploy applications
• ✅ Rollback to previous versions

Use Cases

Scenario	Recommended Mode
Production monitoring	MCP_ALLOW_WRITE=false
Audit/Compliance dashboards	MCP_ALLOW_WRITE=false
Development/Staging	MCP_ALLOW_WRITE=true
Emergency access	Temporarily enable

note

Sync operations with dry_run=true are always allowed in read-only mode.

---

🔌 MCP Client Configuration

The server supports two transport modes: streamable-http (for remote/URL-based connections) and stdio (for local subprocess). SSE mode has been deprecated and is no longer supported.

Step 1: Start the Server

docker run --rm -it \
  -p 8770:8770 \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e MCP_PORT=8770 \
  -e MCP_PATH="/mcp" \
  -e ARGOCD_INSECURE="true" \
  -e MCP_ALLOW_WRITE="true" \
  talkopsai/argocd-mcp-server:latest

The server listens on http://localhost:8770/mcp.

Step 2: Configure the Client

For streamable-http (URL-based connection), add this to your MCP client config (e.g. mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "argocd-mcp-server": {
      "url": "http://localhost:8770/mcp",
      "disabled": false,
      "disabledTools": []
    }
  }
}

That's all the client needs. The URL implies streamable-http transport.

---

🔧 Troubleshooting

Connection Timeout Errors

If you see timeouts, ensure the server is reachable at http://localhost:8770/mcp. Some clients allow optional timeout and connect_timeout overrides if needed.

ArgoCD Connection Errors

Error: ArgoCDConnectionError: Failed to connect to ArgoCD

Solutions:

1. Verify ARGOCD_SERVER_URL is correct
2. Check ARGOCD_AUTH_TOKEN is valid
3. Ensure ArgoCD server is accessible
4. Try with ARGOCD_INSECURE=true for dev environments

Repository Onboarding Failures

Error: GIT_PASSWORD environment variable is not set

Solution:

export GIT_PASSWORD="ghp_your_github_token"

Generate token at: https://github.com/settings/tokens (requires repo scope)

Error: SSH key not found

Solution:

export SSH_PRIVATE_KEY_PATH="~/.ssh/id_rsa"
chmod 600 ~/.ssh/id_rsa

Write Operations Blocked

Error: ArgoCD [operation] is not allowed

Solution:

export MCP_ALLOW_WRITE="true"
# Restart the server

---

Next Steps

• 🛠️ Tools - Available MCP tools reference
• 📁 Resources and Prompts - MCP resources and prompts
• 📖 Examples - Usage patterns and workflows