MCP 服务器

Traefik MCP Server

Enables AI assistants to query and manage Traefik reverse proxy configurations, including routers, services, and middlewares, through natural language. It supports monitoring service health, viewing statistics, and performing administrative tasks across various providers like Docker.

README

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

Clone the repository:

git clone <repository-url>
cd traefik-mcp

Create virtual environment and install dependencies:

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

Configure environment variables:

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

Option 2: Docker Setup

Clone the repository:

git clone <repository-url>
cd traefik-mcp

Build the Docker image:
```
docker build -t traefik-mcp .
```

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 enabled in your configuration

Authentication failures

Verify basic auth credentials match your Traefik configuration
If using API key, ensure it's correctly formatted
API key takes precedence over basic auth if both are set

Connection errors

Check that TRAEFIK_API_URL is reachable from the MCP server
Verify Traefik is running and API is enabled
Check network/firewall settings

Testing the Server

You can test the MCP server manually:

# Set environment variables and run
export TRAEFIK_API_URL="http://localhost:8080"
export TRAEFIK_BASIC_AUTH_USERNAME="admin"
export TRAEFIK_BASIC_AUTH_PASSWORD="admin"
uv run traefik-mcp