Skip to content

README.md

Latest commit

 

History

History
198 lines (152 loc) · 5.73 KB

README.md

File metadata and controls

198 lines (152 loc) · 5.73 KB

Argo Workflows MCP Server

Model Context Protocol (MCP) server for interacting with Argo Workflows. This server enables Claude Desktop and Claude Code to manage and monitor Argo Workflows directly.

Features

  • List and monitor workflows
  • Manage workflow templates
  • Handle cron workflows
  • Query workflow status and logs
  • Execute workflow operations with configurable permissions

Building

# Build the application
./gradlew installDist

# Run tests
./gradlew test

Configuration with Claude Desktop

Add this to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Using the claude CLI

claude mcp add --transport stdio argo-workflows \
  -- docker run -i --rm \
    -e ARGO_BASE_URL=http://host.docker.internal:2746 \
    -e ARGO_NAMESPACE=default \
    -e MCP_ALLOW_MUTATIONS=true \
    -e MCP_AUDIT_FILE=/app/logs/mcp-audit.log \
    -v "$HOME/.kube/config:/home/mcp/.kube/config:ro" \
    -v "$HOME/.argo-mcp-logs:/app/logs" \
    ghcr.io/heapy/argo-workflows-mcp:main

After running the command restart Claude Desktop so it reloads the MCP list.

Using Docker

{
  "mcpServers": {
    "argo-workflows": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ARGO_BASE_URL=http://host.docker.internal:2746",
        "-e", "ARGO_NAMESPACE=default",
        "-e", "MCP_ALLOW_MUTATIONS=true",
        "-e", "MCP_AUDIT_FILE=/app/logs/mcp-audit.log",
        "-v", "/Users/your-user/.kube/config:/home/mcp/.kube/config:ro",
        "-v", "/Users/your-user/.argo-mcp-logs:/app/logs",
        "ghcr.io/heapy/argo-workflows-mcp:main"
      ]
    }
  }
}

Configuration with Claude Code

Add this to your Claude Code MCP configuration file:

Location: ~/.config/claude-code/mcp_config.json

Using Docker

{
  "mcpServers": {
    "argo-workflows": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ARGO_BASE_URL=http://host.docker.internal:2746",
        "-e", "ARGO_NAMESPACE=default",
        "-e", "MCP_ALLOW_MUTATIONS=true",
        "-e", "MCP_AUDIT_FILE=/app/logs/mcp-audit.log",
        "-v", "/Users/your-user/.kube/config:/home/mcp/.kube/config:ro",
        "-v", "/Users/your-user/.argo-mcp-logs:/app/logs",
        "ghcr.io/heapy/argo-workflows-mcp:main"
      ]
    }
  }
}

Docker Usage

Using the published image

Images are published to GitHub Container Registry by CI:

  • ghcr.io/heapy/argo-workflows-mcp:main — latest build from main
  • ghcr.io/heapy/argo-workflows-mcp:<git-sha> — immutable build per commit
docker run -it --rm \
  -e ARGO_BASE_URL=https://your-argo-server:2746 \
  -e ARGO_NAMESPACE=default \
  -e ARGO_TOKEN=$(cat ~/secrets/argo-token) \
  -e MCP_AUDIT_FILE=/app/logs/mcp-audit.log \
  -v /Users/your-user/.kube/config:/home/mcp/.kube/config:ro \
  -v /Users/your-user/.argo-mcp-logs:/app/logs \
  ghcr.io/heapy/argo-workflows-mcp:main

Building locally

# Build the application first
./gradlew installDist

# Build Docker image
docker build -t argo-workflows-mcp:latest .

# Run with docker-compose
docker-compose up

# Or run directly
docker run -it --rm \
  -e ARGO_BASE_URL=http://your-argo-server:2746 \
  -e ARGO_NAMESPACE=default \
  -e ARGO_TOKEN=your-token \
  -e MCP_AUDIT_FILE=/app/logs/mcp-audit.log \
  -v $(pwd)/logs:/app/logs \
  argo-workflows-mcp:latest

If the TLS certificate is issued for another host (for example localhost while you access the server via host.docker.internal), set ARGO_TLS_SERVER_NAME to the certificate hostname so the client presents the correct SNI value.

Environment Variables

Server Configuration

  • MCP_SERVER_NAME - Server name (default: argo-workflows-mcp)
  • MCP_SERVER_VERSION - Server version (default: 0.1.0)

Argo Workflows Connection

  • ARGO_BASE_URL - Argo Workflows API URL (default: http://localhost:2746)
  • ARGO_NAMESPACE - Default Kubernetes namespace (default: default)
  • ARGO_TOKEN - Bearer token for authentication
  • ARGO_USERNAME - Username for basic auth
  • ARGO_PASSWORD - Password for basic auth
  • ARGO_INSECURE_SKIP_TLS_VERIFY - Skip TLS verification (default: false)
  • ARGO_TLS_SERVER_NAME - Override TLS server name / SNI value when establishing TLS connections
  • ARGO_REQUEST_TIMEOUT_SECONDS - Request timeout (default: 30)

Kubernetes Configuration

  • KUBECONFIG - Path to kubeconfig file
  • KUBE_CONTEXT - Kubernetes context to use

Permissions

  • MCP_ALLOW_DESTRUCTIVE - Allow destructive operations like delete (default: false)
  • MCP_ALLOW_MUTATIONS - Allow mutations like create/update (default: false)
  • MCP_REQUIRE_CONFIRMATION - Require confirmation for sensitive operations (default: true)
  • MCP_NAMESPACES_ALLOW - Comma-separated list of allowed namespaces (default: *)
  • MCP_NAMESPACES_DENY - Comma-separated list of denied namespaces (default: empty)

Logging

  • MCP_AUDIT_ENABLED - Enable audit logging (default: true)
  • MCP_AUDIT_FILE - Audit log file path (default: ./mcp-audit.log)
  • MCP_LOG_LEVEL - Log level: debug, info, warn, error (default: info)

Security Notes

  • By default, the server runs in read-only mode
  • Set MCP_ALLOW_MUTATIONS=true to enable create/update operations
  • Set MCP_ALLOW_DESTRUCTIVE=true to enable delete operations
  • Use MCP_NAMESPACES_ALLOW to restrict access to specific namespaces
  • All operations are logged when MCP_AUDIT_ENABLED=true

Development

This project uses:

  • Kotlin with coroutines
  • Gradle 9.2.0
  • Java 25
  • MCP Kotlin SDK
  • Generated Argo Workflows client from OpenAPI spec

See AGENTS.md for development guidelines.