Skip to main content
Glama
Traefik MCP Server

Traefik MCP Server

by theupriser

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.

Related MCP server: ContainMind

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 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

Project Status

✅ Phase 1 Complete - Core functionality implemented

  • Traefik API integration with authentication

  • All query tools working correctly

  • Support for both API key and basic authentication

  • Comprehensive error handling

🚧 Phase 2 Planned - Management features

  • Dynamic configuration updates

  • Service health monitoring

  • Advanced filtering and search

See TASKS.md for current development tasks and PLANNING.md for project roadmap.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - See LICENSE file for details

Resources

Available Tools

6 tools
get_router_detailsC

Get detailed configuration for a specific router

Inputs: router_name (required), provider.

get_service_detailsC

Get detailed configuration for a specific service

Inputs: service_name (required), provider.

get_traefik_overviewB

Get an overview of the Traefik instance configuration

Inputs: no named parameters.

list_middlewaresC

List all HTTP middlewares in Traefik

Inputs: provider.

list_routersC

List all HTTP routers in Traefik

Inputs: provider.

list_servicesB

List all HTTP services in Traefik

Inputs: provider.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose targeting specific resources in Traefik: three 'get' tools for detailed configuration of routers, services, and the overall instance, and three 'list' tools for enumerating middlewares, routers, and services. There is no overlap or ambiguity in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with clear and descriptive naming. The verbs 'get' and 'list' are used appropriately, and nouns like 'router_details', 'service_details', and 'traefik_overview' maintain a uniform structure throughout.

    Tool Count5/5

    With 6 tools, the server is well-scoped for managing a Traefik instance. It provides essential read operations for configuration overview and details, which is appropriate for monitoring and inspection purposes without being overly complex or sparse.

    Completeness3/5

    The tool set covers read operations thoroughly for routers, services, middlewares, and overall configuration, but there are notable gaps for write operations like creating, updating, or deleting resources. This limits the server to inspection-only workflows, which may be insufficient for full management.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Docker containers, deploy stacks, and monitor services across multiple Docker hosts from one centralized location. Supports container lifecycle management, Docker Compose operations, and infrastructure orchestration through natural language commands.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage and analyze containers across Docker and Podman through natural language, providing unified inspection, monitoring, and diagnostics.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Nginx Proxy Manager instances through natural language, covering 28 tools for proxy hosts, certificates, streams, and more.
      MIT