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](https://github.com/astral-sh/uv) package manager - A running Traefik instance with API enabled ### Option 1: Local Development Setup 1. Clone the repository: ```bash git clone <repository-url> cd traefik-mcp ``` 2. Create virtual environment and install dependencies: ```bash uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]" ``` 3. Configure environment variables: ```bash cp .env.example .env # Edit .env with your Traefik API URL and credentials ``` ### Option 2: Docker Setup 1. Clone the repository: ```bash git clone <repository-url> cd traefik-mcp ``` 2. Build the Docker image: ```bash docker build -t traefik-mcp . ``` 3. Run the container: ```bash # 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 ```bash uv run traefik-mcp ``` ### Integration with AI Clients #### Claude Desktop Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```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) ```json { "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) ```json { "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 ```bash pytest ``` ### Code Formatting ```bash black src/ tests/ ruff check src/ tests/ ``` ### Type Checking ```bash 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: ```bash # 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](TASKS.md) for current development tasks and [PLANNING.md](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 - [Traefik Documentation](https://doc.traefik.io/traefik/) - [MCP Documentation](https://modelcontextprotocol.io/) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)