Traefik MCP Server

Managing Kubernetes traffic is painful. Between brittle Ingress YAML, messy NGINX annotations, and digging through docs to figure out Middleware configurations, even a simple task like adding a rate limiter takes way too long. And if you want an AI assistant to handle this, it struggles because there's no safe, structured way for it to interact with Traefik's custom resources.

This server fixes that. It gives AI assistants (Claude, Cline, or your own agent) direct MCP tools to manage your Kubernetes traffic through Traefik — safely and automatically. Instead of writing YAML by hand, your AI can now confidently create routes, attach protections, split traffic, and even migrate off NGINX.

Three things make this different:

Automated NGINX-to-Traefik Migrations. The AI scans your old Ingress files, analyzes the annotations (CORS, sticky sessions, auth), and converts them into modern Traefik CRDs. If it detects a legacy config that would break the migration, it can use built-in "Supervised Autonomy" to bypass the broken rule and build a custom workaround.
One-Command Traffic Control. Need to test a new version? Ask the AI to split traffic 90/10, set up a shadow launch where live traffic is copied to your new app silently, or create header-based canary routes. All through natural language.
Instant Middleware Generation. Tell the AI "Add a rate limit and circuit breaker to the frontend" — it builds and attaches the Traefik Middleware CRDs immediately. No YAML templates required.

Key Features

Edge Routing & Traffic Splitting

Create weighted canary routes with exact percentages (e.g., 90/10)
Path-based, header-based, and cookie-based routing
TLS termination with secret binding
Simple direct IngressRoutes for non-canary traffic

Middleware Generation

Rate limiting, circuit breakers, retry logic
Strip prefix, redirect scheme, IP allowlists/denylists
Forward auth, buffering, header manipulation
Attach and detach middlewares on live routes

NGINX Migration & Supervised Autonomy

Scan existing NGINX Ingress resources and annotations
Full compatibility analysis (cluster-wide or per-namespace)
Generate or apply Traefik CRD bundles automatically
Agentic overrides for breaking legacy annotations (ignore + inject custom middleware)
One-command revert per Ingress

Traffic Mirroring (Shadow Launch)

Copy a percentage of production traffic to a new version silently
User responses always come from stable — zero user impact
Enable, disable, or adjust mirror percentage on the fly

TCP Routing

Route PostgreSQL, Redis, MQTT, or any TCP protocol through Traefik
SNI-based routing and TLS passthrough
TCP-specific IP allowlist middleware

Deep Network Observability

Real-time traffic distribution (weights, percentages, middleware state)
Error rate and latency metrics via Prometheus
Anomaly detection and historical audit logs

Multi-Cluster Support

Switch between Kubernetes contexts via K8S_CONTEXT

Architecture

The server translates high-level MCP requests into Kubernetes API calls through a layered service architecture.

How it works in practice:

An AI assistant connects to the server over HTTP (or stdio)
It reads current cluster state via MCP resources (traffic distribution, route configs, anomalies)
When a user asks something like "Add a rate limit to the API," the assistant calls the appropriate tool
The service layer patches the Traefik CRDs via the Kubernetes API
Traffic changes take effect immediately

Tech Stack

Category	Technologies
Language	Python 3.10+
MCP Framework	FastMCP
Protocol	Model Context Protocol (MCP)
Kubernetes	Traefik CRDs · kubectl · Python K8s Client
Transport	HTTP · stdio
Infrastructure	Docker · uv

Quick Start

You'll need a running Kubernetes cluster with Traefik Ingress Controller installed, a valid kubeconfig, and Docker or Python 3.10+.

Docker (recommended):

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

Point your MCP client at it (e.g. in mcp.json or .cursor/mcp.json):

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

Security

Never hardcode credentials in BasicAuth middleware — use Kubernetes Secrets
Use namespace isolation and RBAC to restrict which resources the server can modify
Set MCP_ALLOW_WRITE=false to prevent cluster mutations (YAML generation still works)
Review generated manifests (action=generate) before applying to production clusters

Project Layout

traefik-mcp-server/
├── traefik_mcp_server/
│   ├── tools/           # MCP Tools (traffic, middleware, migrations, TCP)
│   ├── resources/       # Traffic distribution, metrics, anomalies, migration status
│   ├── services/        # Traefik service wrapper, YAML generator
│   ├── server/          # FastMCP setup
│   ├── exceptions/      # Error definitions
│   ├── config.py        # Environment parsing
│   └── main.py          # Entry point
├── tests/               # Test suites
├── Dockerfile
├── pyproject.toml
└── README.md

Next Steps

Configuration — Environment variables, Docker setup, and access control
Tools — Full reference for all MCP tools
Resources — Real-time data streams and monitoring
Common Workflows — Step-by-step workflow guides
Examples — Quick reference and prompts

Key Features​

Architecture​

Tech Stack​

Quick Start​

Security​

Project Layout​

Next Steps​