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 authenticationTRAEFIK_BASIC_AUTH_USERNAME: Username for basic authenticationTRAEFIK_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 componentslist_routers: List all HTTP routers (optional provider filter)get_router_details: Get detailed configuration for a specific routerlist_services: List all HTTP services (optional provider filter)get_service_details: Get detailed configuration for a specific servicelist_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_URLis 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