# How to use the Docker MCP server

- Tool: MCP
- Difficulty: Intermediate
- Time required: 15 minutes
- Compatibility: Claude Desktop, Cursor, Windsurf, VS Code (Copilot)
- Last updated: March 2026

## TL;DR

The Docker MCP server lets your AI assistant manage Docker containers, images, volumes, and networks directly from your chat window. It can list running containers, start and stop services, view logs, inspect configurations, and help debug containerized applications. Configure it to connect to your local Docker daemon, and your AI becomes a hands-on DevOps assistant that understands your container infrastructure and can take action on it.

## Manage Docker Containers from Your AI Assistant

The Docker MCP server connects your AI assistant to your local Docker daemon, exposing tools to manage containers, images, volumes, and networks. Instead of memorizing Docker CLI commands, you can ask your AI to list running containers, check logs for errors, restart failed services, inspect container configurations, and manage the entire lifecycle of your Docker infrastructure. This is especially valuable for developers working with multi-container applications, Docker Compose stacks, and local development environments that rely on containerized services like databases, caches, and message queues.

## Before you start

- Docker Desktop or Docker Engine installed and running
- Node.js 18 or later installed on your machine
- Claude Desktop, Cursor, or another MCP-compatible AI host
- Basic familiarity with Docker concepts (containers, images, volumes)

## Step-by-step guide

### 1. Verify Docker is running

Before configuring the MCP server, make sure Docker is installed and the daemon is running. Open a terminal and run 'docker ps' to verify. If you see a list of containers (or an empty list), Docker is working. If you get a connection error, start Docker Desktop or the Docker service first.

```
# Verify Docker is running:
docker ps

# Expected output (even if no containers):
# CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES
```

**Expected result:** Docker is installed and the daemon is running, confirmed by the docker ps command working.

### 2. Add the Docker MCP server to your configuration

Open your MCP host's configuration file and add a docker entry. The Docker MCP server connects to the Docker daemon socket on your machine. The configuration uses npx with the -y flag for automatic installation.

```
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-docker"
      ]
    }
  }
}
```

**Expected result:** Your configuration file contains the Docker MCP server entry.

### 3. Restart your AI host and verify the connection

Fully quit and reopen Claude Desktop, Cursor, or VS Code. The Docker MCP server will connect to your local Docker daemon. Its tools for container, image, volume, and network management should appear in the available tools list.

**Expected result:** The Docker MCP server shows as connected with container management tools available.

### 4. List and inspect running containers

Start with read-only operations to verify the connection. Ask the AI to list your running containers, inspect specific containers, or show resource usage. The AI translates your natural language requests into Docker API calls.

```
Example prompts:

"List all running Docker containers with their ports and status"

"Show me the configuration of the postgres container"

"What Docker images are currently downloaded on my machine?"
```

**Expected result:** The AI returns a list of containers, images, and their details from your Docker environment.

### 5. View logs and debug container issues

One of the most valuable use cases is debugging. Ask the AI to check container logs for errors, inspect environment variables, or investigate why a container is failing. The AI can read logs, parse error messages, and suggest fixes — all through natural language.

```
Example prompts:

"Show me the last 50 lines of logs from the api-server container"

"Check if the redis container has any error messages in its logs"

"Why is the postgres container restarting? Show me its logs and exit code"
```

**Expected result:** The AI retrieves container logs and provides analysis of errors or issues found.

### 6. Start, stop, and manage container lifecycle

The AI can start, stop, restart, and remove containers. It can also pull images, create containers from images, and manage Docker Compose stacks. Always review the action in Claude Desktop's approval dialog before confirming, especially for destructive operations like removing containers or volumes.

```
Example prompts:

"Stop the old-api container and remove it"

"Restart the postgres container"

"Pull the latest nginx:alpine image and create a new container running on port 8080"
```

**Expected result:** The AI performs the requested container lifecycle operations and confirms the results.

## Complete code example

File: `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-docker"
      ]
    }
  }
}

// VS Code variant (.vscode/mcp.json):
// {
//   "servers": {
//     "docker": {
//       "command": "npx",
//       "args": ["-y", "@modelcontextprotocol/server-docker"]
//     }
//   }
// }

// No API keys required — connects to local Docker daemon.
// Docker must be running before starting the MCP server.

// Available tools:
// - list_containers: List running containers (optionally all)
// - inspect_container: Get detailed container configuration
// - container_logs: View container log output
// - start_container: Start a stopped container
// - stop_container: Stop a running container
// - restart_container: Restart a container
// - remove_container: Remove a stopped container
// - list_images: List downloaded Docker images
// - pull_image: Download an image from a registry
// - list_volumes: List Docker volumes
// - list_networks: List Docker networks
// - create_container: Create a new container from an image
```

## Common mistakes

- **Starting the MCP server before Docker is running** — undefined Fix: The Docker MCP server needs to connect to the Docker daemon on startup. Make sure Docker Desktop is running before you launch your AI host. If the server fails, restart your AI host after starting Docker.
- **Removing containers or volumes without understanding the impact** — undefined Fix: Always review destructive actions in the approval dialog. Removing a container does not remove its volumes by default, but removing a volume deletes all data in it permanently. Ask the AI to list what would be affected before confirming.
- **Running the MCP server without proper Docker socket permissions** — undefined Fix: On Linux, the Docker socket requires permission to access. Your user must be in the docker group or you need to run with appropriate permissions. On macOS with Docker Desktop, this is handled automatically.
- **Asking the AI to manage production containers from a local machine** — undefined Fix: The Docker MCP server connects to the local Docker daemon only. It cannot manage remote Docker hosts or cloud container services (ECS, Cloud Run, etc.) without additional configuration. Use it for local development environments.

## Best practices

- Ensure Docker is running before starting your AI host
- Use specific container names rather than IDs when telling the AI what to manage
- Review all destructive operations (remove, prune) in the approval dialog before confirming
- Start with read-only operations (list, inspect, logs) before performing actions
- Combine with the filesystem MCP server so the AI can read docker-compose.yml files
- Use the AI to analyze container logs for errors rather than scrolling through them manually
- Keep your Docker environment clean — ask the AI to identify unused images and stopped containers
- Back up important volume data before letting the AI remove or modify containers

## Frequently asked questions

### Can the Docker MCP server manage Docker Compose stacks?

The server operates at the Docker daemon level, managing individual containers, images, and volumes. It can see containers started by Docker Compose, but it does not directly parse docker-compose.yml files. Combine with the filesystem MCP server to have the AI read your Compose file and understand the full stack.

### Can the AI pull and run any Docker image?

Yes, the AI can pull images from Docker Hub and other registries, then create and start containers from them. Always review the image name and configuration in the approval dialog to avoid running untrusted images.

### Does it work with Docker on remote servers?

By default, the server connects to the local Docker daemon socket. Connecting to remote Docker hosts requires configuring the DOCKER_HOST environment variable, which involves security considerations like SSH tunneling or TLS certificates.

### Can I use this with Podman instead of Docker?

Podman provides a Docker-compatible socket. If Podman is configured with its socket enabled, the MCP server may work with it. However, this is not officially tested and some commands may behave differently.

### Will the AI accidentally delete important containers?

In Claude Desktop, all destructive operations require your explicit approval in a confirmation dialog. The AI will not remove containers, images, or volumes without your permission. Always read the confirmation carefully.

### Can RapidDev help me set up a containerized development environment with MCP?

Yes. RapidDev can help design Docker-based development environments with proper multi-container orchestration, MCP server integration for AI-assisted management, and CI/CD pipelines for containerized deployments.

---

Source: https://www.rapidevelopers.com/mcp-tutorial/how-to-use-docker-mcp-server
© RapidDev — https://www.rapidevelopers.com/mcp-tutorial/how-to-use-docker-mcp-server