Docker MCP Server

A Model Context Protocol (MCP) server providing Docker management tools for Claude Code.

Overview

This MCP server exposes Docker functionality through MCP tools, allowing Claude to interact with Docker containers, images, networks, and volumes.

Features

Tools for Docker operations including:

• Container management (list, start, stop, inspect)
• Image management (list, pull, build)
• Network operations
• Volume management
• Docker Compose integration

Installation

Prerequisites

• Python 3.11 or higher
• Docker installed and running
• uv package manager (recommended) or pip

Setup

# Install dependencies
uv sync

# Or with pip
pip install -e .

Usage

Option 1: Run with Docker (Recommended)

Build and Run with Docker Compose

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

Build and Run with Docker CLI

# Build the image
docker build -t docker-mcp-server .

# Run the container (Linux/macOS)
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker-mcp-server

# Run the container (Windows)
docker run -it --rm \
  -v //var/run/docker.sock:/var/run/docker.sock \
  docker-mcp-server

Important: The -v flag mounts the Docker socket, allowing the container to manage the host's Docker daemon.

Configure with Claude Code (Docker)

# Add the Docker-based server
claude mcp add --transport stdio docker -- docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker-mcp-server

Or configure in .mcp.json:

{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "docker-mcp-server"
      ]
    }
  }
}

Option 2: Run with Python (Local Development)

Add the server to your Claude Code configuration:

claude mcp add --transport stdio docker -- python /path/to/custom-docker-mcp-server/server.py

Or configure in .mcp.json:

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Standalone Testing

Test the server using MCP Inspector:

# With Docker
docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker-mcp-server | mcp-inspector

# With Python
mcp-inspector -- python server.py

Available Tools

list_containers

Lists all running Docker containers with detailed information.

Parameters: None

Returns:

• Container ID (short form)
• Container name
• Image name/tag
• Status
• Port mappings

Example usage:

User: "Show me all running containers"
Claude: Uses list_containers tool
Result: Displays formatted list of running containers

Development

Project Structure

custom-docker-mcp-server/
├── src/                    # Business logic
│   ├── __init__.py        # Package initialization
│   └── containers.py      # Container operations
├── server.py              # Main MCP server implementation
├── pyproject.toml         # Project configuration
├── Dockerfile             # Docker image definition
├── docker-compose.yml     # Docker Compose configuration
├── .dockerignore          # Docker build exclusions
├── README.md              # This file
└── .gitignore            # Git ignore rules

Adding New Tools

Tools are implemented using the FastMCP framework with business logic separated in the src/ directory:

1. Add business logic in appropriate module under src/ (e.g., src/containers.py)
2. Define the MCP tool in server.py using @mcp.tool() decorator
3. Import and call the business logic from the tool

See server.py and src/containers.py for examples.

Requirements

• Docker Engine API access
• Appropriate permissions to manage Docker resources

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.