Docker

What is mcp-server-docker?

mcp-server-docker is an MCP (Multi-Container Platform) server that allows users to manage Docker containers, images, volumes, and networks using natural language. It integrates with Docker to provide a conversational interface for Docker operations.

How to use mcp-server-docker?

mcp-server-docker can be installed via PyPi with uv or by running it as a Docker container. Once installed, it can be configured in your Claude Desktop MCP servers file. Users interact with the server through natural language prompts, such as docker_compose to create and manage containers.

Key Features of mcp-server-docker

• Natural Language Control: Compose, introspect, and debug Docker containers using natural language.
• Container Management: Tools for listing, creating, running, recreating, starting, stopping, and removing containers.
• Image Management: Tools for listing, pulling, pushing, building, and removing Docker images.
• Network Management: Tools for listing, creating, and removing Docker networks.
• Volume Management: Tools for listing, creating, and removing Docker volumes.
• Resource Monitoring: Provides stats (CPU, memory) and logs for containers.
• Remote Docker Connection: Can connect to a remote Docker daemon over SSH.

Use Cases of mcp-server-docker

• Server Administrators: Manage remote Docker engines for public-facing websites or other services.
• Tinkerers: Experiment with open-source applications locally using Docker.
• AI Enthusiasts: Explore the capabilities of Large Language Models (LLMs) in controlling infrastructure.
• Automated Deployment: Compose and manage container deployments with natural language instructions.

FAQ about mcp-server-docker

• Can I use sensitive data with mcp-server-docker? No, it is strongly advised NOT to configure containers with sensitive data like API keys or database passwords, as any sensitive data exchanged with the LLM is inherently compromised unless the LLM is running locally.
• Is mcp-server-docker a secure sandbox? No, Docker is not a secure sandbox. Users should carefully review containers created by the LLM, as the MCP server can potentially impact the host machine. Sensitive Docker options like --privileged or --cap-add/--cap-drop are not supported for safety reasons.
• How does mcp-server-docker connect to Docker? It uses the Python Docker SDK's from_env method and can connect to a remote Docker daemon over SSH by setting the DOCKER_HOST environment variable.

🐋 Docker MCP server

An MCP server for managing Docker with natural language!

🪩 What can it do?

• 🚀 Compose containers with natural language
• 🔍 Introspect & debug running containers
• 📀 Manage persistent data with Docker volumes

❓ Who is this for?

• Server administrators: connect to remote Docker engines for e.g. managing a public-facing website.
• Tinkerers: run containers locally and experiment with open-source apps supporting Docker.
• AI enthusiasts: push the limits of that an LLM is capable of!

Demo

A quick demo showing a WordPress deployment using natural language:

https://github.com/user-attachments/assets/65e35e67-bce0-4449-af7e-9f4dd773b4b3

🏎️ Quickstart

Install

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

If you don't have uv installed, follow the installation instructions for your system: link

Then add the following to your MCP servers file:

"mcpServers": {
  "mcp-server-docker": {
    "command": "uvx",
    "args": [
      "mcp-server-docker"
    ]
  }
}

Purely for convenience, the server can run in a Docker container.

After cloning this repository, build the Docker image:

docker build -t mcp-server-docker .

And then add the following to your MCP servers file:

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

Note that we mount the Docker socket as a volume; this ensures the MCP server can connect to and control the local Docker daemon.

📝 Prompts

🎻 docker_compose

Use natural language to compose containers. See above for a demo.

Provide a Project Name, and a description of desired containers, and let the LLM do the rest.

This prompt instructs the LLM to enter a plan+apply loop. Your interaction with the LLM will involve the following steps:

1. You give the LLM instructions for which containers to bring up
2. The LLM calculates a concise natural language plan and presents it to you
3. You either:
   • Apply the plan
   • Provide the LLM feedback, and the LLM recalculates the plan

Examples

• name: nginx, containers: "deploy an nginx container exposing it on port 9000"
• name: wordpress, containers: "deploy a WordPress container and a supporting MySQL container, exposing Wordpress on port 9000"

Resuming a Project

When starting a new chat with this prompt, the LLM will receive the status of any containers, volumes, and networks created with the given project name.

This is mainly useful for cleaning up, in-case you lose a chat that was responsible for many containers.

📔 Resources

The server implements a couple resources for every container:

• Stats: CPU, memory, etc. for a container
• Logs: tail some logs from a container

🔨 Tools

Containers

• list_containers
• create_container
• run_container
• recreate_container
• start_container
• fetch_container_logs
• stop_container
• remove_container

Images

• list_images
• pull_image
• push_image
• build_image
• remove_image

Networks

• list_networks
• create_network
• remove_network

Volumes

• list_volumes
• create_volume
• remove_volume

🚧 Disclaimers

Sensitive Data

DO NOT CONFIGURE CONTAINERS WITH SENSITIVE DATA. This includes API keys, database passwords, etc.

Any sensitive data exchanged with the LLM is inherently compromised, unless the LLM is running on your local machine.

If you are interested in securely passing secrets to containers, file an issue on this repository with your use-case.

Reviewing Created Containers

Be careful to review the containers that the LLM creates. Docker is not a secure sandbox, and therefore the MCP server can potentially impact the host machine through Docker.

For safety reasons, this MCP server doesn't support sensitive Docker options like --privileged or --cap-add/--cap-drop. If these features are of interest to you, file an issue on this repository with your use-case.

🛠️ Configuration

This server uses the Python Docker SDK's from_env method. For configuration details, see the documentation.

Connect to Docker over SSH

This MCP server can connect to a remote Docker daemon over SSH.

Simply set a ssh:// host URL in the MCP server definition:

"mcpServers": {
  "mcp-server-docker": {
    "command": "uvx",
    "args": [
      "mcp-server-docker"
    ],
    "env": {
      "DOCKER_HOST": "ssh://myusername@myhost.example.com"
    }
  }
}

💻 Development

Prefer using Devbox to configure your development environment.

See the devbox.json for helpful development commands.

After setting up devbox you can configure your Claude MCP config to use it:

  "docker": {
    "command": "/path/to/repo/.devbox/nix/profile/default/bin/uv",
    "args": [
      "--directory",
      "/path/to/repo/",
      "run",
      "mcp-server-docker"
    ]
  },