container-manager-mcp 1.12.0

Container Manager - manage Docker, Docker Swarm, and Podman containers. MCP+A2A Servers Out of the Box!

Container Manager - A2A | AG-UI | MCP

Version: 1.12.0

Overview

Container Manager provides a robust universal interface to manage Docker and Podman containers, networks, volumes, and Docker Swarm services, enabling programmatic and remote container management.

This is package contains an MCP Server + A2A Server Out of the Box!

This repository is actively maintained - Contributions are welcome!

Features

• Manage Docker and Podman containers, images, volumes, and networks
• Support for Docker Swarm operations
• Support for Docker Compose and Podman Compose operations
• FastMCP server for remote API access
• Comprehensive logging and error handling
• Extensible architecture for additional container runtimes
• Multi-agent A2A system for delegated container management

MCP

Available MCP Tools

This server utilizes dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Tool Name	Description
container_compose	Consolidated Action-Routed tool for compose. Methods: compose_up, compose_down, compose_ps
container_container	Consolidated Action-Routed tool for container. Methods: stop_container, run_container, remove_container, prune_containers, exec_in_container, list_containers
container_image	Consolidated Action-Routed tool for image. Methods: prune_images, remove_image, pull_image, list_images
container_info	Consolidated Action-Routed tool for info. Methods: get_version, get_info
container_log	Consolidated Action-Routed tool for log. Methods: compose_logs
container_network	Consolidated Action-Routed tool for network. Methods: prune_networks, create_network, list_networks, remove_network
container_swarm	Consolidated Action-Routed tool for swarm. Methods: list_nodes, list_services, init_swarm, remove_service, create_service, leave_swarm
container_system	Consolidated Action-Routed tool for system. Methods: prune_system
container_volume	Consolidated Action-Routed tool for volume. Methods: list_volumes, remove_volume, prune_volumes, create_volume

A2A Agent

A2A CLI

Endpoints

• Web UI: http://localhost:8000/ (if enabled)
• A2A: http://localhost:8000/a2a (Discovery: /a2a/.well-known/agent.json)
• AG-UI: http://localhost:8000/ag-ui (POST)

Long Flag	Description
--host	Host to bind the server to (default: 0.0.0.0)
--port	Port to bind the server to (default: 9000)
--provider	LLM Provider: openai, anthropic, google, huggingface (default: openai)
--model-id	LLM Model ID (default: nvidia/nemotron-3-super)
--base-url	LLM Base URL (for OpenAI compatible providers)
--api-key	LLM API Key
--mcp-url	MCP Server URL (default: http://localhost:8000/mcp)
--web	Enable Pydantic AI Web UI

Graph Architecture

This agent uses pydantic-graph orchestration for intelligent routing and optimal context management.

---
title: Container Manager MCP Graph Agent
---
stateDiagram-v2
  [*] --> RouterNode: User Query
  RouterNode --> DomainNode: Classified Domain
  RouterNode --> [*]: Low confidence / Error
  DomainNode --> [*]: Domain Result

• RouterNode: A fast, lightweight LLM (e.g., nvidia/nemotron-3-super) that classifies the user's query into one of the specialized domains.
• DomainNode: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., gpt-4o) to complete the request. This preserves LLM context and prevents tool hallucination.

Usage

Using as an MCP Server

The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:

Run in stdio mode (default):

container-manager-mcp

Run in HTTP mode:

container-manager-mcp --transport "http"  --host "0.0.0.0"  --port "8000"

Deploy MCP Server as a Service

The ServiceNow MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.

Using Docker Run

docker pull knucklessg1/container-manager:latest

docker run -d \
  --name container-manager-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=streamable-http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  knucklessg1/container-manager:latest

Run A2A Agent (Docker):

docker run -d \
  --name container-manager-agent \
  -p 9000:9000 \
  -e PORT=9000 \
  -e PROVIDER=openai \
  -e MODEL_ID=nvidia/nemotron-3-super \
  -e BASE_URL=http://host.docker.internal:11434/v1 \
  -e MCP_URL=http://host.docker.internal:8004/mcp \
  knucklessg1/container-manager:latest \
  container-manager-agent

For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:

docker run -d \
  --name container-manager-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=streamable-http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  knucklessg1/container-manager:latest

Using Docker Compose

Create a docker-compose.yml file:

services:
  container-manager-mcp:
    image: knucklessg1/container-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=streamable-http
      - AUTH_TYPE=none
      - EUNOMIA_TYPE=none
    ports:
      - 8004:8004

For advanced setups with authentication and Eunomia:

services:
  container-manager-mcp:
    image: knucklessg1/container-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=streamable-http
      - AUTH_TYPE=oidc-proxy
      - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_BASE_URL=https://your-server.com
      - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
      - EUNOMIA_TYPE=embedded
      - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
    ports:
      - 8004:8004
    volumes:
      - ./mcp_policies.json:/app/mcp_policies.json

Run the service:

docker-compose up -d

Configure mcp.json for AI Integration

{
  "mcpServers": {
    "container_manager": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "container-manager-mcp",
        "container-manager-mcp"
      ],
      "env": {
        "CONTAINER_MANAGER_SILENT": "False",                                  //Optional
        "CONTAINER_MANAGER_LOG_FILE": "~/Documents/container_manager_mcp.log" //Optional
        "CONTAINER_MANAGER_TYPE": "podman",                                   //Optional
        "CONTAINER_MANAGER_PODMAN_BASE_URL": "tcp://127.0.0.1:8080"           //Optional
      },
      "timeout": 200000
    }
  }
}

Install Python Package

python -m pip install container-manager-mcp

or

uv pip install --upgrade container-manager-mcp

Test

container-manager-mcp --transport streamable-http --host 127.0.0.1 --port 8080

This starts the MCP server using HTTP transport on localhost port 8080.

To interact with the MCP server programmatically, you can use a FastMCP client or make HTTP requests to the exposed endpoints. Example using curl to pull an image:

curl -X POST http://127.0.0.1:8080/pull_image \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx", "tag": "latest", "manager_type": "docker"}'

Install the Python package:

python -m pip install container-manager-mcp

Dependencies

• Python 3.7+
• fastmcp for MCP server functionality
• docker for Docker support
• podman for Podman support
• pydantic for data validation

Install dependencies:

python -m pip install fastmcp docker podman pydantic

Ensure Docker or Podman is installed and running on your system.

Development and Contribution

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add your feature')
4. Push to the branch (git push origin feature/your-feature)
5. Create a new Pull Request

Please ensure your code follows the project's coding standards and includes appropriate tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Repository Owners

MCP Configuration Examples

1. Standard IO (stdio) Deployment

{
  "mcpServers": {
    "container-manager-mcp": {
      "command": "uv",
      "args": [
        "run",
        "container-manager-mcp"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "COMPOSETOOL": "True",
        "CONTAINERTOOL": "True",
        "CONTAINER_MANAGER_LOG_FILE": "<YOUR_CONTAINER_MANAGER_LOG_FILE>",
        "CONTAINER_MANAGER_PODMAN_BASE_URL": "<YOUR_CONTAINER_MANAGER_PODMAN_BASE_URL>",
        "CONTAINER_MANAGER_SILENT": "<YOUR_CONTAINER_MANAGER_SILENT>",
        "CONTAINER_MANAGER_TYPE": "<YOUR_CONTAINER_MANAGER_TYPE>",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "IMAGETOOL": "True",
        "INFOTOOL": "True",
        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
        "LOGTOOL": "True",
        "MCP_URL": "<YOUR_MCP_URL>",
        "MISCTOOL": "True",
        "MODEL_ID": "<YOUR_MODEL_ID>",
        "NETWORKTOOL": "True",
        "SPECIALIST_TOOL": "True",
        "SWARMTOOL": "True",
        "SYSTEMTOOL": "True",
        "VOLUMETOOL": "True"
      }
    }
  }
}

2. Streamable HTTP (SSE) Deployment

{
  "mcpServers": {
    "container-manager-mcp": {
      "command": "uv",
      "args": [
        "run",
        "container-manager-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
        "COMPOSETOOL": "True",
        "CONTAINERTOOL": "True",
        "CONTAINER_MANAGER_LOG_FILE": "<YOUR_CONTAINER_MANAGER_LOG_FILE>",
        "CONTAINER_MANAGER_PODMAN_BASE_URL": "<YOUR_CONTAINER_MANAGER_PODMAN_BASE_URL>",
        "CONTAINER_MANAGER_SILENT": "<YOUR_CONTAINER_MANAGER_SILENT>",
        "CONTAINER_MANAGER_TYPE": "<YOUR_CONTAINER_MANAGER_TYPE>",
        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
        "IMAGETOOL": "True",
        "INFOTOOL": "True",
        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
        "LOGTOOL": "True",
        "MCP_URL": "<YOUR_MCP_URL>",
        "MISCTOOL": "True",
        "MODEL_ID": "<YOUR_MODEL_ID>",
        "NETWORKTOOL": "True",
        "SPECIALIST_TOOL": "True",
        "SWARMTOOL": "True",
        "SYSTEMTOOL": "True",
        "VOLUMETOOL": "True"
      }
    }
  }
}