🐳 MCP Container Tools

PyPI version Python 3.11+ License: MIT MCP

A Model Context Protocol (MCP) server for Docker, Kubernetes, and Azure Application Insights with advanced log filtering and monitoring capabilities.

✨ Features

🐳 Docker — Container logs, inspect, exec, list containers
🐙 Docker Compose — Service logs, start/stop/restart services
☸️ Kubernetes — Pod logs, deployment logs, events, exec into pods
☁️ Azure Application Insights — Exceptions, traces, requests, metrics
🔍 Log Filtering — Filter by log level, regex patterns, exclude patterns
🌐 Remote Support — Connect to remote Docker hosts via SSH or TCP

📋 Requirements

Requirement	Version	Required For
🐍 Python	3.11+	All
🐳 Docker	Latest	Docker tools
☸️ kubectl	Latest	Kubernetes tools
☁️ Azure CLI	Latest	Azure tools (optional)

🚀 Installation

📦 Quick Install (recommended)

# Basic installation
pip install mcp-container-tools

# With Azure Application Insights support
pip install mcp-container-tools[azure]

🐙 Install from GitHub

# Latest version from GitHub
pip install git+https://github.com/simseksem/mcp-container-tools.git

# With Azure support
pip install "mcp-container-tools[azure] @ git+https://github.com/simseksem/mcp-container-tools.git"

🔧 Install from source (for development)

git clone https://github.com/simseksem/mcp-container-tools.git
cd mcp-container-tools
pip install -e ".[all]"

✅ Verify installation

mcp-server --help

⚙️ Configuration

🖥️ Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "container-tools": {
      "command": "/path/to/mcp-container-tools/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "AZURE_LOG_ANALYTICS_WORKSPACE_ID": "your-workspace-id",
        "AZURE_APP_INSIGHTS_RESOURCE_ID": "/subscriptions/.../resourceGroups/.../providers/microsoft.insights/components/..."
      }
    }
  }
}

💻 Claude Code

Add to ~/.claude/settings.json or create .mcp.json in your project:

{
  "mcpServers": {
    "container-tools": {
      "command": "/path/to/mcp-container-tools/.venv/bin/python",
      "args": ["-m", "mcp_server.server"]
    }
  }
}

☁️ Azure Authentication

Azure tools use DefaultAzureCredential which supports:

Azure CLI (az login)
Environment variables
Managed Identity
Visual Studio Code

# Easiest: Login with Azure CLI
az login

📖 Usage Examples

🐳 Docker

# Read container logs
docker_logs(container="my-app", tail=100)

# Read logs from last 30 minutes
docker_logs(container="my-app", since="30m")

# Filter by log level (only errors and above)
docker_logs(container="my-app", min_level="error")

# Search for patterns
docker_logs(container="my-app", pattern="timeout|connection refused")

# Exclude health checks
docker_logs(container="my-app", exclude_pattern="GET /health")

# Remote Docker host via SSH
docker_logs(container="my-app", host="ssh://user@server.com")

# List containers
docker_ps(all=True)

🐙 Docker Compose

# Read service logs
compose_logs(service="api", tail=200)

# Read all services logs
compose_logs(project_dir="/path/to/project")

# Service management
compose_up(service="api", project_dir="/path/to/project")
compose_down(project_dir="/path/to/project")
compose_restart(service="api")

☸️ Kubernetes

# Read pod logs
k8s_logs(pod="api-7d4b8c6f9-x2k4m", namespace="production")

# Read logs from all pods in a deployment
k8s_deployment_logs(deployment="api", namespace="production")

# Filter logs
k8s_logs(pod="api-*", min_level="warn", pattern="database")

# Use different context
k8s_logs(pod="my-pod", context="production-cluster", namespace="backend")

# List pods
k8s_pods(namespace="all", selector="app=api")

# Get events
k8s_events(namespace="production")

# Execute command in pod
k8s_exec(pod="api-xyz", command="printenv", namespace="production")

☁️ Azure Application Insights

# Query exceptions from last hour
azure_exceptions(timespan="PT1H", limit=50)

# Get only critical exceptions
azure_exceptions(severity="critical", search="NullReference")

# Query application traces
azure_traces(timespan="PT1H", severity="error")

# Query HTTP requests
azure_requests(timespan="PT1H", failed_only=True)

# Get slow requests (>1 second)
azure_requests(min_duration_ms=1000, limit=20)

# Query external dependencies (SQL, HTTP, etc.)
azure_dependencies(timespan="PT1H", failed_only=True, type_filter="SQL")

# Get metrics
azure_metrics(metric_name="requests/count", timespan="P1D", interval="PT1H")

# Query availability test results
azure_availability(timespan="P1D", failed_only=True)

# Run custom Kusto query
azure_query(query="""
    requests
    | where success == false
    | summarize count() by bin(timestamp, 1h), resultCode
    | order by timestamp desc
""", timespan="P1D")

🔍 Log Filtering Options

All log tools support these filtering options:

Option	Description	Example
`min_level`	Minimum log level	`"error"`, `"warn"`, `"info"`
`pattern`	Regex to include	`"error\|exception"`
`exclude_pattern`	Regex to exclude	`"health.*check"`
`context_lines`	Lines around matches	`5`

Supported log levels: trace → debug → info → warn → error → fatal

⏱️ Timespan Format (Azure)

Azure tools use ISO 8601 duration format:

Format	Duration
`PT1H`	1 hour
`PT30M`	30 minutes
`P1D`	1 day
`P7D`	7 days

🛠️ Available Tools

🐳 Docker Tools

Tool	Description
`docker_logs`	📄 Read container logs with filtering
`docker_ps`	📋 List containers
`docker_inspect`	🔎 Get container details
`docker_exec`	⚡ Execute command in container

🐙 Docker Compose Tools

Tool	Description
`compose_logs`	📄 Read service logs
`compose_ps`	📋 List services
`compose_up`	▶️ Start services
`compose_down`	⏹️ Stop services
`compose_restart`	🔄 Restart services

☸️ Kubernetes Tools

Tool	Description
`k8s_logs`	📄 Read pod logs
`k8s_deployment_logs`	📚 Read deployment logs
`k8s_pods`	📋 List pods
`k8s_describe`	🔎 Describe pod
`k8s_exec`	⚡ Execute in pod
`k8s_events`	📢 Get events
`k8s_contexts`	🌐 List contexts

☁️ Azure Application Insights Tools

Tool	Description
`azure_query`	🔍 Run custom Kusto queries
`azure_exceptions`	❌ Query application exceptions
`azure_traces`	📝 Query application traces
`azure_requests`	🌐 Query HTTP requests
`azure_dependencies`	🔗 Query external dependencies
`azure_metrics`	📊 Query metrics
`azure_availability`	✅ Query availability tests

👨‍💻 Development

Install dev dependencies

pip install -e ".[all]"

Run tests

pytest

Linting and type checking

ruff check .
mypy src/

📁 Project Structure

mcp-container-tools/
├── 📂 src/mcp_server/
│   ├── 📄 __init__.py
│   ├── 📄 server.py               # Main server entry point
│   ├── 📂 tools/
│   │   ├── 🐳 docker.py           # Docker tools
│   │   ├── 🐙 docker_compose.py   # Compose tools
│   │   ├── ☸️ kubernetes.py        # K8s tools
│   │   ├── ☁️ azure_insights.py    # Azure App Insights
│   │   └── 📁 file_operations.py  # File tools
│   ├── 📂 resources/
│   │   ├── ⚙️ config.py           # Config resources
│   │   └── 📊 data.py             # Data resources
│   ├── 📂 prompts/
│   │   └── 📝 templates.py        # Prompt templates
│   └── 📂 utils/
│       └── 🔍 log_filter.py       # Log filtering
├── 📂 tests/
├── 📄 pyproject.toml
└── 📄 README.md

🔐 Environment Variables

Variable	Description
`AZURE_LOG_ANALYTICS_WORKSPACE_ID`	Azure Log Analytics workspace ID
`AZURE_APP_INSIGHTS_RESOURCE_ID`	Azure Application Insights resource ID

📄 License

MIT License - see LICENSE for details.