Traefik MCP Server

Traefik MCP Server

A Model Context Protocol (MCP) server for managing and interacting with Traefik reverse proxy instances through AI assistants.

Overview

This MCP server enables AI assistants to query and manage Traefik configurations, monitor service health, and perform administrative tasks through natural language interactions.

Features

• 🔍 Query Traefik routers, services, and middlewares
• 📊 Get comprehensive Traefik overview and statistics
• ⚙️ View detailed configuration for individual components
• 🔒 Support for both API key and basic authentication
• 🚀 Async operations for optimal performance
• 🛠️ Provider-specific filtering (Docker, file, etc.)

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager
• A running Traefik instance with API enabled

Option 1: Local Development Setup

1. Clone the repository:

   git clone <repository-url>
   cd traefik-mcp
   

2. Create virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e ".[dev]"
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your Traefik API URL and credentials
   

Option 2: Docker Setup

1. Clone the repository:

   git clone <repository-url>
   cd traefik-mcp
   

2. Build the Docker image:

   docker build -t traefik-mcp .
   

3. Run the container:

   # Basic run
   docker run -it --rm traefik-mcp
   
   # With environment variables
   docker run -it --rm \
     -e TRAEFIK_API_URL=http://traefik:8080 \
     -e TRAEFIK_BASIC_AUTH_USERNAME=admin \
     -e TRAEFIK_BASIC_AUTH_PASSWORD=admin \
     traefik-mcp
   
   # Background service
   docker run -d --name traefik-mcp \
     -e TRAEFIK_API_URL=http://traefik:8080 \
     -e TRAEFIK_BASIC_AUTH_USERNAME=admin \
     -e TRAEFIK_BASIC_AUTH_PASSWORD=admin \
     traefik-mcp
   

Configuration

Set the following environment variables:

Required

• TRAEFIK_API_URL: URL of your Traefik API endpoint (e.g., http://localhost:8080)

Authentication (choose one)

• TRAEFIK_API_KEY: API key for Bearer token authentication
• TRAEFIK_BASIC_AUTH_USERNAME: Username for basic authentication
• TRAEFIK_BASIC_AUTH_PASSWORD: Password for basic authentication

Optional

• MCP_LOG_LEVEL: Logging level (default: INFO)

Note: API key authentication takes precedence over basic authentication if both are configured.

Usage

Running the Server

uv run traefik-mcp

Integration with AI Clients

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "traefik": {
      "command": "/path/to/traefik-mcp/.venv/bin/traefik-mcp",
      "args": [],
      "env": {
        "TRAEFIK_API_URL": "http://localhost:8080",
        "TRAEFIK_BASIC_AUTH_USERNAME": "admin",
        "TRAEFIK_BASIC_AUTH_PASSWORD": "admin"
      }
    }
  }
}

Claude Desktop (Docker)

{
  "mcpServers": {
    "traefik": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "traefik-mcp"
      ],
      "env": {
        "TRAEFIK_API_URL": "http://localhost:8080",
        "TRAEFIK_BASIC_AUTH_USERNAME": "admin",
        "TRAEFIK_BASIC_AUTH_PASSWORD": "admin"
      }
    }
  }
}

Alternative (using uv)

{
  "mcpServers": {
    "traefik": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/traefik-mcp",
        "run",
        "traefik-mcp"
      ],
      "env": {
        "TRAEFIK_API_URL": "http://localhost:8080"
      }
    }
  }
}

Available Tools

The MCP server provides the following tools:

• get_traefik_overview: Get comprehensive overview of all Traefik components
• list_routers: List all HTTP routers (optional provider filter)
• get_router_details: Get detailed configuration for a specific router
• list_services: List all HTTP services (optional provider filter)
• get_service_details: Get detailed configuration for a specific service
• list_middlewares: List all HTTP middlewares (optional provider filter)

Example Usage

Once configured with Claude Desktop, you can ask questions like:

• "Show me all routers in my Traefik setup"
• "What services are running behind the traefik.test router?"
• "List all middlewares configured for Docker provider"
• "Give me an overview of my Traefik instance"

Development

Running Tests

pytest

Code Formatting

black src/ tests/
ruff check src/ tests/

Type Checking

mypy src/

Troubleshooting

Common Issues

Server shows 0 routers/services

• Ensure your Traefik API is accessible at the configured URL
• Verify authentication credentials are correct
• Check that Traefik API is ena