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

# Option 1: Using environment variables (recommended)
export ARGOCD_SERVER="https://localhost:8080"
export ARGOCD_USERNAME="admin"
export ARGOCD_PASSWORD="your-password"
export ARGOCD_VERIFY_TLS="false"  # For self-signed certs

python fetch_argocd_token.py

# Option 2: Using command-line arguments
python fetch_argocd_token.py \
  --server https://localhost:8080 \
  --username admin \
  --password your-password \
  --insecure

# Option 3: Get export command directly
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 sandeep2014/talkops-mcp:argocd-mcp-server-latest

# Run with default configuration (read-only mode)
docker run --rm -it \
  -p 8765:8765 \
  -v ~/.ssh/id_ed25519:/app/.ssh/id_rsa:ro \
  -e ARGOCD_SERVER_URL="https://argocd.example.com" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e SSH_PRIVATE_KEY_PATH=/app/.ssh/id_rsa \
  sandeep2014/talkops-mcp:argocd-mcp-server-latest

# Run with write access enabled
docker run --rm -it \
  -p 8765:8765 \
  -v ~/.ssh/id_ed25519:/app/.ssh/id_rsa:ro \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e ARGOCD_INSECURE="true" \
  -e SSH_PRIVATE_KEY_PATH=/app/.ssh/id_rsa \
  -e MCP_ALLOW_WRITE="true" \
  sandeep2014/talkops-mcp: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 8765:8765 \
  -v ~/.ssh/id_ed25519:/app/.ssh/id_rsa:ro \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e SSH_PRIVATE_KEY_PATH=/app/.ssh/id_rsa \
  -e ARGOCD_INSECURE="true" \
  -e MCP_ALLOW_WRITE="true" \
  sandeep2014/talkops-mcp: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	http	Transport mode: http or stdio
MCP_HOST	0.0.0.0	Host address for HTTP/SSE server
MCP_PORT	8765	Port for HTTP/SSE server
MCP_PATH	/sse	SSE endpoint path
MCP_ALLOW_WRITE	false	Enable write operations (see below)
MCP_HTTP_TIMEOUT	300	HTTP request timeout in seconds
MCP_HTTP_KEEPALIVE_TIMEOUT	5	HTTP keepalive timeout in seconds
MCP_HTTP_CONNECT_TIMEOUT	60	HTTP connection timeout in seconds
MCP_LOG_LEVEL	INFO	Logging level
MCP_LOG_FORMAT	json	Log format: json or text

ArgoCD Configuration

Variable	Default	Description
ARGOCD_SERVER_URL	https://argocd-server.argocd.svc:443	ArgoCD server URL
ARGOCD_AUTH_TOKEN	(required)	ArgoCD API authentication token
ARGOCD_INSECURE	false	Skip TLS verification
ARGOCD_TIMEOUT	300	Timeout for ArgoCD 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

Step 1: Start the Server

docker run --rm -it \
  -p 8765:8765 \
  -v ~/.ssh/id_ed25519:/app/.ssh/id_rsa:ro \
  -e ARGOCD_SERVER_URL="https://host.docker.internal:8080" \
  -e ARGOCD_AUTH_TOKEN="your-token-here" \
  -e ARGOCD_INSECURE="true" \
  -e SSH_PRIVATE_KEY_PATH=/app/.ssh/id_rsa \
  -e MCP_ALLOW_WRITE="true" \
  sandeep2014/talkops-mcp:argocd-mcp-server-latest

Expected output:

🚀 Starting ArgoCD MCP Server
📋 Configuration:
   Server: argocd-mcp-server v0.1.0
   Transport: http
   Listen: 0.0.0.0:8765/sse
   Write Mode: true
   Log Level: INFO

🔗 ArgoCD Configuration:
   Server URL: https://host.docker.internal:8080
   Auth Token: ***SET***
   Insecure: true

✅ Starting server...
INFO:     Uvicorn running on http://0.0.0.0:8765

Step 2: Configure the Client

{
  "mcpServers": {
    "argocd-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8765/sse",
      "description": "ArgoCD MCP Server for GitOps application management",
      "disabled": false,
      "autoApprove": [],
      "timeout": 300.0,
      "connect_timeout": 60.0
    }
  }
}

---

🔧 Troubleshooting

Connection Timeout Errors

Increase client timeout values:

{
  "url": "http://localhost:8765/sse",
  "transport": "sse",
  "timeout": 300.0,
  "connect_timeout": 60.0
}

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