container-manager-mcp 1.12.1

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

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

Security & Governance

This project is built on agent-utilities, inheriting enterprise-grade security and governance features.

Authentication & Authorization

Feature	Description
OIDC Token Delegation	RFC 8693 token exchange for user-context propagation from A2A → MCP
Eunomia Policies	Fine-grained, policy-driven tool authorization (none, embedded, remote)
Scoped Credentials	Tools execute with the caller's scoped identity where possible
3LO / OAuth / API Token	Multiple auth strategies with graceful fallback

Eunomia Policy Enforcement

Eunomia provides a policy enforcement point for all tool calls:

• Embedded mode: Load local mcp_policies.json for role-based access, sensitivity gating, and audit logging
• Remote mode: Forward authorization decisions to a central Eunomia policy server for multi-agent governance
• Enable via CLI: --eunomia-type embedded --eunomia-policy-file mcp_policies.json

Runtime Protections

Protection	Description
Tool Guard	Sensitivity detection with human-in-the-loop approval gating
Prompt Injection Defense	Input scanning and repetition/loop guards
Content Filtering	Output schema enforcement and cost budget controls
Stuck Loop Detection	Automatic detection and recovery from agent loops
Context Limit Warnings	Proactive alerts before context window exhaustion

Graph Agent Architecture

The A2A agent uses pydantic-graph orchestration with:

• RouterNode: Lightweight classifier that routes queries to specialized domains
• DomainNode: Focused executor with only relevant tools loaded, preventing tool hallucination
• Approval Gates: Policy-driven approval workflows before sensitive operations
• Usage Guards: Budget and rate limiting enforcement

Production Recommendation: Enable --eunomia-type embedded (or remote) + OIDC delegation + containerized deployment. See agent-utilities documentation for full policy configuration.

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

stdio (recommended for local development)

{
  "mcpServers": {
    "container-manager": {
      "command": ".venv/bin/container-manager-mcp",
      "args": [],
      "env": {
        "CONTAINER_MANAGER_TYPE": "docker"
}
    }
  }
}

Streamable HTTP (recommended for production)

{
  "mcpServers": {
    "container-manager": {
      "url": "http://localhost:8080/container-manager-mcp/mcp"
    }
  }
}