Docker MCP Server

Overview

The Docker MCP server provides comprehensive container lifecycle management, image operations, network administration, and volume management. It's essential for Aegis infrastructure operations and deployment automation.

Tool Prefix: mcp__docker__

Repository: https://github.com/docker/mcp-server-docker

Container Management

list_containers

mcp__docker__list_containers(all: bool = False)

List running containers. Set all=True to include stopped containers.

Returns:

{
  "containers": [
    {
      "id": "abc123",
      "name": "nginx",
      "image": "nginx:latest",
      "status": "running",
      "ports": ["80:80", "443:443"],
      "created": "2026-01-20T10:00:00Z"
    }
  ]
}

Example:

# List running containers
containers = await mcp__docker__list_containers()

# List all containers including stopped
all_containers = await mcp__docker__list_containers(all=True)

inspect_container

mcp__docker__inspect_container(container_id: str)

Get detailed container information including configuration, networks, volumes, and resource usage.

start_container

mcp__docker__start_container(container_id: str)

Start a stopped container.

stop_container

mcp__docker__stop_container(
    container_id: str,
    timeout: int = 10
)

Stop a running container. Sends SIGTERM, then SIGKILL after timeout.

restart_container

mcp__docker__restart_container(
    container_id: str,
    timeout: int = 10
)

Restart a container.

remove_container

mcp__docker__remove_container(
    container_id: str,
    force: bool = False,
    volumes: bool = False
)

Remove a container. Use force=True to kill and remove. Use volumes=True to remove associated volumes.

run_container

mcp__docker__run_container(
    image: str,
    name: str = None,
    ports: dict = None,
    environment: dict = None,
    volumes: dict = None,
    command: str = None,
    detach: bool = True,
    network: str = None,
    restart_policy: str = "no"
)

Create and start a new container.

Example:

await mcp__docker__run_container(
    image="nginx:latest",
    name="web-server",
    ports={"80/tcp": 8080, "443/tcp": 8443},
    environment={"ENV": "production"},
    volumes={"/data": {"bind": "/app/data", "mode": "rw"}},
    network="aegis-net",
    restart_policy="unless-stopped"
)

container_logs

mcp__docker__container_logs(
    container_id: str,
    tail: int = 100,
    since: str = None,
    follow: bool = False
)

Get container logs. Use since="2026-01-20T10:00:00Z" for logs after timestamp.

container_stats

mcp__docker__container_stats(
    container_id: str,
    stream: bool = False
)

Get container resource usage statistics (CPU, memory, network, disk I/O).

Image Management

list_images

mcp__docker__list_images(all: bool = False)

List images. Set all=True to include intermediate layers.

pull_image

mcp__docker__pull_image(
    image: str,
    tag: str = "latest"
)

Pull an image from a registry.

Example:

await mcp__docker__pull_image("postgres", tag="16-alpine")

build_image

mcp__docker__build_image(
    path: str,
    tag: str,
    dockerfile: str = "Dockerfile",
    buildargs: dict = None,
    nocache: bool = False
)

Build an image from a Dockerfile.

Example:

await mcp__docker__build_image(
    path="/home/agent/projects/aegis-core",
    tag="aegis:latest",
    dockerfile="Dockerfile",
    buildargs={"VERSION": "1.0.0"}
)

push_image

mcp__docker__push_image(
    image: str,
    tag: str = "latest"
)

Push an image to a registry.

tag_image

mcp__docker__tag_image(
    source: str,
    target: str
)

Tag an image.

remove_image

mcp__docker__remove_image(
    image: str,
    force: bool = False
)

Remove an image.

prune_images

mcp__docker__prune_images(all: bool = False)

Remove unused images. Set all=True to remove all unused images (not just dangling).

Network Management

list_networks

mcp__docker__list_networks()

List all Docker networks.

create_network

mcp__docker__create_network(
    name: str,
    driver: str = "bridge",
    subnet: str = None,
    gateway: str = None
)

Create a network.

Example:

await mcp__docker__create_network(
    name="aegis-net",
    driver="bridge",
    subnet="172.20.0.0/16",
    gateway="172.20.0.1"
)

inspect_network

mcp__docker__inspect_network(network_id: str)

Get detailed network information including connected containers.

connect_container_to_network

mcp__docker__connect_container_to_network(
    container_id: str,
    network_id: str,
    aliases: list = None
)

Connect a container to a network.

disconnect_container_from_network

mcp__docker__disconnect_container_from_network(
    container_id: str,
    network_id: str,
    force: bool = False
)

Disconnect a container from a network.

remove_network

mcp__docker__remove_network(network_id: str)

Remove a network.

prune_networks

mcp__docker__prune_networks()

Remove all unused networks.

Volume Management

list_volumes

mcp__docker__list_volumes()

List all volumes.

create_volume

mcp__docker__create_volume(
    name: str,
    driver: str = "local",
    driver_opts: dict = None,
    labels: dict = None
)

Create a volume.

Example:

await mcp__docker__create_volume(
    name="postgres-data",
    labels={"app": "postgres", "env": "production"}
)

inspect_volume

mcp__docker__inspect_volume(volume_name: str)

Get detailed volume information.

remove_volume

mcp__docker__remove_volume(
    volume_name: str,
    force: bool = False
)

Remove a volume.

prune_volumes

mcp__docker__prune_volumes()

Remove all unused volumes.

Docker Compose Integration

compose_up

mcp__docker__compose_up(
    project_path: str,
    services: list = None,
    detach: bool = True,
    build: bool = False
)

Start services defined in docker-compose.yml.

Example:

await mcp__docker__compose_up(
    project_path="/home/agent/projects/aegis-core",
    detach=True,
    build=True
)

compose_down

mcp__docker__compose_down(
    project_path: str,
    volumes: bool = False,
    remove_orphans: bool = True
)

Stop and remove containers defined in docker-compose.yml.

compose_ps

mcp__docker__compose_ps(project_path: str)

List containers for a Compose project.

compose_logs

mcp__docker__compose_logs(
    project_path: str,
    services: list = None,
    tail: int = 100
)

View logs for Compose services.

System Operations

system_info

mcp__docker__system_info()

Get Docker system information (version, storage driver, resources).

system_df

mcp__docker__system_df()

Show disk usage for images, containers, volumes, and build cache.

system_prune

mcp__docker__system_prune(
    all: bool = False,
    volumes: bool = False
)

Remove unused data (containers, networks, images, build cache).

WARNING: Potentially destructive. Use with caution.

Common Patterns

Health Check Pattern

# Check all Aegis containers
containers = await mcp__docker__list_containers()
for container in containers.containers:
    if "aegis" in container.name.lower():
        stats = await mcp__docker__container_stats(container.id)
        logs = await mcp__docker__container_logs(container.id, tail=50)
        print(f"{container.name}: {container.status}")

Deployment Pattern

# Pull latest image
await mcp__docker__pull_image("aegis/dashboard", tag="latest")

# Stop old container
old = await mcp__docker__list_containers(all=True)
for c in old.containers:
    if c.name == "aegis-dashboard":
        await mcp__docker__stop_container(c.id)
        await mcp__docker__remove_container(c.id)

# Start new container
await mcp__docker__run_container(
    image="aegis/dashboard:latest",
    name="aegis-dashboard",
    ports={"8080/tcp": 8080},
    network="aegis-net",
    restart_policy="unless-stopped"
)

Cleanup Pattern

# Remove stopped containers
await mcp__docker__prune_containers()

# Remove unused images
await mcp__docker__prune_images(all=False)

# Remove unused volumes
await mcp__docker__prune_volumes()

# Remove unused networks
await mcp__docker__prune_networks()

Integration with Aegis

With StackWiz

StackWiz uses Docker MCP for local operations before deploying to Dockerhost:

# Build locally
await mcp__docker__build_image(
    path="/home/agent/projects/aegis-core",
    tag="aegis/service:latest"
)

# Test locally
await mcp__docker__run_container(
    image="aegis/service:latest",
    name="test-service",
    ports={"8080/tcp": 8080}
)

# Deploy to Dockerhost via StackWiz
await mcp__stackwiz__create_stack(
    name="aegis-service",
    image="aegis/service:latest",
    ...
)

With Monitoring

from aegis.mcp import discover_tools

# Discover Docker tools
docker_tools = await discover_tools(["docker"])

# Get container stats for monitoring
for container in running_containers:
    stats = await mcp__docker__container_stats(container.id)
    if stats.memory_usage > threshold:
        await mcp__discord__discord_send(
            channel_id=ALERTS_CHANNEL,
            content=f"High memory usage on {container.name}"
        )

Configuration

Socket Access

The Docker MCP server requires access to the Docker socket:

{
  "mcpServers": {
    "docker": {
      "command": "docker-mcp",
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

For remote Docker hosts:

{
  "env": {
    "DOCKER_HOST": "tcp://10.10.10.10:2375"
  }
}

Permissions

Ensure the user running MCP has Docker socket access:

sudo usermod -aG docker $USER

Security Considerations

1. Socket Exposure: Docker socket provides root-equivalent access. Use with caution.
2. Prune Operations: System prune can remove production data. Always verify before pruning.
3. Network Isolation: Use custom networks to isolate services.
4. Resource Limits: Set memory and CPU limits on containers:

   await run_container(
       image="nginx",
       mem_limit="512m",
       cpus="0.5"
   )
   

Performance Tips

1. Use Image Tags: Avoid latest in production. Use specific versions.
2. Multi-Stage Builds: Reduce image size with multi-stage Dockerfiles.
3. Volume Mounts: Use volumes for persistent data, not bind mounts.
4. Logging Drivers: Configure JSON logging with max-size to prevent disk fill.
5. Health Checks: Define HEALTHCHECK in Dockerfiles for automated monitoring.

Troubleshooting

"Permission denied" accessing Docker socket

# Add user to docker group
sudo usermod -aG docker agent
# Restart session or:
newgrp docker

Container won't start

# Check logs
logs = await mcp__docker__container_logs(container_id, tail=200)

# Inspect configuration
config = await mcp__docker__inspect_container(container_id)

Out of disk space

# Check disk usage
usage = await mcp__docker__system_df()

# Clean up
await mcp__docker__system_prune(volumes=True)

Next Steps

• StackWiz MCP - Deployment automation
• Aegis MCP - Orchestration tools
• MCP Overview - Protocol basics

References

• Docker MCP Server
• Docker API Documentation
• Aegis Deployment Guide