Skip to main content

Configuration

Complete configuration guide for the Traefik MCP Server including environment variables, Docker setup, MCP client configuration, and troubleshooting.

Prerequisites​

RequirementDescription
Kubernetes ClusterRunning cluster (v1.24+) with valid kubeconfig
TraefikTraefik Ingress Controller installed with CRDs (IngressRoute, TraefikService, Middleware)
kubectlConfigured with cluster access
Python 3.10+For local installation (optional)

Installation Options​

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

# Run with default configuration
docker run --rm -it \
  -p 8769:8769 \
  -v ~/.kube/config:/app/.kube/config:ro \
  talkopsai/traefik-mcp-server:latest

# Run with custom context and debug logging
docker run --rm -it \
  -p 8769:8769 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e K8S_CONTEXT=production-cluster \
  -e MCP_LOG_LEVEL=DEBUG \
  talkopsai/traefik-mcp-server:latest

Option 2: From Source (Python)​

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

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

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run the server
uv run traefik-mcp-server

Run tests (with the venv activated):

pytest tests/

Environment Variables​

Server Configuration​

VariableDefaultDescription
MCP_SERVER_NAMEtraefik-mcp-serverServer name identifier
MCP_SERVER_VERSION0.1.0Server version string
MCP_TRANSPORThttpTransport mode: http or stdio
MCP_HOST0.0.0.0Host address for HTTP server
MCP_PORT8769Port for HTTP server
MCP_PATH/mcpMCP endpoint path
MCP_LOG_LEVELINFOLog level: DEBUG, INFO, WARNING, ERROR
MCP_LOG_FORMATjsonLog format: json or text

Edge & Kubernetes​

VariableDefaultDescription
K8S_KUBECONFIG/app/.kube/configPath to kubeconfig file
K8S_CONTEXT(empty)Specific K8s context to force
K8S_IN_CLUSTERfalseSet to true if running inside a pod
MCP_ALLOW_WRITEtrueEnables cluster-mutating operations (e.g., traefik_nginx_migration with action=apply). When false, only YAML generation and read operations work.

Write Access Control​

MCP_ALLOW_WRITE=true (default) allows in-cluster apply operations for the NGINX migration pipeline and other mutating tools. When set to false, mutating actions are blocked but YAML-only generation (action=generate) still works.

Required RBAC Permissions​

OperationResourcesVerbs
Read paths (inventory, analysis)ingresses, podsget, list, watch
Apply paths (migration, routing)middlewares, serverstransports (traefik.io/v1alpha1)create, patch, update
Apply paths (continued)ingresses, servicespatch

MCP Client Configuration​

The server listens on http://localhost:8769/mcp by default. Add this to your MCP client config (e.g. mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "traefik": {
      "url": "http://localhost:8769/mcp",
      "description": "MCP Server for managing Traefik Edge Routing and Middlewares"
    }
  }
}

Troubleshooting​

Connection Errors​

If your MCP client cannot reach port 8769:

  1. Verify the server is running (docker ps or check the process)
  2. Check your kubeconfig mount is correct: -v ~/.kube/config:/app/.kube/config:ro
  3. Ensure port 8769 is not in use by another process
  4. If using Docker Desktop, you may need --network host

K8s Connectivity​

  1. Ensure your cluster context matches K8S_CONTEXT (if set)
  2. Verify kubeconfig: kubectl cluster-info
  3. For in-cluster deployments, set K8S_IN_CLUSTER=true

Migration Issues​

If NGINX migration generates unexpected results:

  1. Check resource naming — the migration tool maps NGINX annotation names to Traefik CRD names
  2. Use traefik://migration/nginx-ingress-analyze to see the full compatibility analysis before applying
  3. For unsupported annotations, use the migration_plan parameter with ignore_annotations and inject_middlewares

MCP Client Timeouts​

Set your MCP client's HTTP timeout to at least 30 seconds. The NGINX migration scan can take longer on large clusters with many Ingress resources.

Next Steps​