Configuration

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

---

Prerequisites

Requirement	Description
Kubernetes Cluster	Running cluster (v1.24+) with valid kubeconfig
Traefik	Traefik Ingress Controller installed with CRDs (IngressRoute, TraefikService, Middleware)
kubectl	Configured with cluster access
Python 3.10+	For local installation (optional)

---

Installation Options

Option 1: Docker (Recommended)

# 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

Variable	Default	Description
MCP_SERVER_NAME	traefik-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 server
MCP_PORT	8769	Port for HTTP server
MCP_PATH	/mcp	MCP endpoint path
MCP_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR
MCP_LOG_FORMAT	json	Log format: json or text

Edge & Kubernetes

Variable	Default	Description
K8S_KUBECONFIG	/app/.kube/config	Path to kubeconfig file
K8S_CONTEXT	(empty)	Specific K8s context to force
K8S_IN_CLUSTER	false	Set to true if running inside a pod
MCP_ALLOW_WRITE	true	Enables 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

Operation	Resources	Verbs
Read paths (inventory, analysis)	ingresses, pods	get, list, watch
Apply paths (migration, routing)	middlewares, serverstransports (traefik.io/v1alpha1)	create, patch, update
Apply paths (continued)	ingresses, services	patch

---

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

• Tools — Available MCP tools reference
• Resources — MCP resources for monitoring
• Common Workflows — Step-by-step workflow guides
• Examples — Quick reference and prompts