Skip to content

USAGE_EXAMPLES.md

Latest commit

 

History

History
365 lines (283 loc) · 5.88 KB

USAGE_EXAMPLES.md

File metadata and controls

365 lines (283 loc) · 5.88 KB

Docker MCP Plugin - Usage Examples

This guide shows how to use the Docker MCP Toolkit plugin with Clawdbot.

Available Docker MCP Tools

The Docker MCP server provides a single powerful tool:

docker tool

Wraps the Docker CLI - accepts any Docker command as arguments.

Parameters:

  • args (array): Arguments to pass to the Docker command

Example Commands

Container Management

List running containers:

You: "List my Docker containers"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["ps"]
}

Show all containers (including stopped):

You: "Show all my Docker containers, including stopped ones"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["ps", "-a"]
}

Inspect a container:

You: "Show me details about the open-webui container"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["inspect", "open-webui"]
}

View container logs:

You: "Show me the logs for automaker-server"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["logs", "automaker-server"]
}

Start/Stop containers:

You: "Stop the open-webui container"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["stop", "open-webui"]
}

Image Management

List images:

You: "What Docker images do I have?"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["images"]
}

Pull an image:

You: "Pull the latest nginx image"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["pull", "nginx:latest"]
}

Remove an image:

You: "Remove the unused postgres image"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["rmi", "postgres"]
}

System Information

Docker version:

You: "What version of Docker am I running?"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["version"]
}

Docker system info:

You: "Show me Docker system information"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["info"]
}

Disk usage:

You: "How much disk space is Docker using?"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["system", "df"]
}

Volume & Network Management

List volumes:

You: "List all Docker volumes"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["volume", "ls"]
}

List networks:

You: "Show me Docker networks"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["network", "ls"]
}

Create a volume:

You: "Create a Docker volume named mydata"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["volume", "create", "mydata"]
}

Docker Compose (if docker-compose server is enabled)

Start services:

You: "Start the services in docker-compose.yml"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["compose", "up", "-d"]
}

Stop services:

You: "Stop all compose services"

Expected tool call:

{
  "tool": "docker_docker",
  "args": ["compose", "down"]
}

Testing Your Installation

Quick Test

Try this simple command in your Clawdbot chat:

You: "List my Docker containers"

Clawdbot should use the docker_docker tool to run docker ps and show you the results.

Verification Steps

  1. Check plugin loaded:

    clawdbot plugins list | grep docker-mcp

    Should show: loaded status

  2. Check Docker is accessible:

    docker ps

    Should list your containers

  3. Test through Clawdbot: Ask Clawdbot to list containers, images, or show Docker info

Expected Behavior

When you ask Docker-related questions:

✅ Good: Clawdbot uses docker_docker tool and returns Docker CLI output
✅ Good: Formatting and explanation of Docker output
❌ Bad: "I don't have access to Docker" (plugin not loaded)
❌ Bad: Error messages about MCP connection (Docker MCP not running)

Troubleshooting

"I don't have Docker tools available"

Check:

  1. Is Docker Desktop installed and running?
  2. Is Docker MCP Toolkit available? (docker mcp --help)
  3. Is the plugin enabled? (check clawdbot.json)
  4. Did you restart Clawdbot after installing?

Fix:

clawdbot plugins enable docker-mcp
clawdbot gateway restart

"MCP connection failed"

Check:

  1. Docker daemon is running: docker ps
  2. Docker MCP gateway can start: docker mcp gateway run --dry-run

Secret warnings on startup

These are normal! Docker MCP checks for all possible secrets. Warnings about missing secrets don't affect functionality.

Advanced Usage

Custom MCP Server Selection

Only enable specific MCP servers:

{
  "plugins": {
    "entries": {
      "docker-mcp": {
        "enabled": true,
        "config": {
          "enabledServers": ["docker", "dockerhub"],
          "timeout": 60000
        }
      }
    }
  }
}

Debug Mode

Enable detailed logging:

{
  "plugins": {
    "entries": {
      "docker-mcp": {
        "config": {
          "debug": true
        }
      }
    }
  }
}

Check logs after restart to see MCP connection details.

Limitations

Current Docker MCP Server

The default docker server provides CLI access only. It doesn't provide high-level semantic tools like "deploy an app" or "scale service to N replicas" - you need to construct the actual Docker commands.

Future Enhancements

As the Docker MCP ecosystem grows, additional servers may provide:

  • Docker Compose semantic operations
  • Docker Swarm management
  • BuildKit build optimization
  • Registry management

Enable new servers by adding them to enabledServers config.

Contributing

Found a useful Docker operation pattern? Add it to this guide!

Submit PRs to: https://github.com/clawdbot/docker-mcp-plugin

Last updated: 2026-01-25