FlorentB974/docker_mcp
If you are the rightful owner of docker_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This is a Model Context Protocol (MCP) server that provides management and insights for Docker containers, images, networks, and volumes.
Docker Agent MCP Server
This is a Model Context Protocol (MCP) server that provides management and insights for Docker containers, images, networks, and volumes. The agent enables interaction with Docker services through MCP tools.
Features
- Deploy Docker compose stacks from chat: give the YAML content directly the prompt
- Remove Docker compose stacks by project name
- Multi-server support: Connect to multiple Docker servers simultaneously via TCP or Unix sockets
- Flexible connection methods: Support for TCP connections and Unix socket connections
- List and manage Docker containers across all servers
- Monitor container statistics and performance
- Analyze logs from containers on any server
- Manage images, networks, and volumes
- Real-time container insights
- Auto-detection of container locations across servers
Prerequisites
- Node.js >= 18
- Docker Engine
- For socket connections: Ensure the Docker socket is accessible (typically
/var/run/docker.sock
on Linux/macOS) - For remote connections: Docker daemon should be configured to accept TCP connections
Installation
- Clone the repository
- Install dependencies:
npm install
- Build the project:
npm run build
Configuration
The Docker agent now supports connecting to multiple Docker servers simultaneously. You can configure this in several ways:
Single Docker Server (Legacy Mode)
For backward compatibility, you can still configure a single Docker server using these environment variables:
DOCKER_HOST
: Docker daemon host address (e.g., "192.168.1.10")DOCKER_PORT
: Docker daemon port (e.g., "2375")DOCKER_PROTOCOL
: Connection protocol ("http" or "https")DOCKER_CERT_PATH
: Path to TLS certificates directory containingca.pem
,cert.pem
, andkey.pem
Multiple Docker Servers
To configure multiple Docker servers, use the DOCKER_SERVERS
environment variable:
DOCKER_SERVERS
: Comma-separated list of server configurations in format:- TCP:
name:host:port:protocol
- Socket:
name:socket:/path/to/socket
- TCP:
DOCKER_CERT_PATH_{SERVER_NAME}
: TLS certificates path for specific servers (optional)
Socket Connections
For local Docker daemon connections via Unix socket, you can configure:
DOCKER_SOCKET
: Path to Docker socket (e.g., "/var/run/docker.sock")- Default fallback: If no configuration is provided, the system will automatically try
/var/run/docker.sock
if it exists
Example configurations:
Single Server
{
"servers": {
"docker-agent": {
"type": "stdio",
"command": "node",
"args": ["./build/index.js"],
"env": {
"DOCKER_HOST": "192.168.1.10",
"DOCKER_PORT": "2375",
"DOCKER_PROTOCOL": "http"
}
}
}
}
Multiple Servers (Mixed TCP and Socket)
{
"servers": {
"docker-agent": {
"type": "stdio",
"command": "node",
"args": ["./build/index.js"],
"env": {
"DOCKER_SERVERS": "production:prod.docker.com:2376:https,staging:staging.docker.com:2375:http,local:socket:/var/run/docker.sock",
"DOCKER_CERT_PATH_PRODUCTION": "/path/to/prod/certs",
"DOCKER_CERT_PATH_STAGING": "/path/to/staging/certs"
}
}
}
}
Socket-only Configuration
{
"servers": {
"docker-agent": {
"type": "stdio",
"command": "node",
"args": ["./build/index.js"],
"env": {
"DOCKER_SOCKET": "/var/run/docker.sock"
}
}
}
}
Default Behavior
If no configuration is provided, the system will automatically:
- Try to connect to
/var/run/docker.sock
if it exists - Fallback to
localhost:2375
via HTTP if the socket is not available
Available Tools
Server Management
list_docker_servers
: List all configured Docker serversadd_docker_server
: Add a new Docker server configuration at runtimeremove_docker_server
: Remove a Docker server configuration
Container Management
All container tools support an optional server
parameter to target a specific Docker server. If not provided, the tool will either operate on all servers or auto-detect the container location.
list_containers
: List Docker containers from all servers or a specific serverget_container_stats
: Get real-time statistics for a container (auto-detects server)start_container
: Start a stopped container (auto-detects server)stop_container
: Stop a running container (auto-detects server)restart_container
: Restart a running container (auto-detects server)remove_container
: Remove a container (auto-detects server)inspect_container
: Get detailed information about a container (auto-detects server)get_container_logs
: Get container logs (auto-detects server)
Image Management
list_images
: List Docker images from all servers or a specific serverpull_image
: Pull a Docker image on a specific server (requires server parameter)remove_image
: Remove a Docker image from a specific server (requires server parameter)
Network & Volume Management
list_networks
: List Docker networks from all servers or a specific serverlist_volumes
: List Docker volumes from all servers or a specific server
Compose Management
run_docker_compose
: Run a Docker Compose YAML provided in the prompt on a specific serverremove_docker_compose
: Remove a Docker Compose project by project name on a specific server.
⚠️ Safety notes ⚠️
- The MCP server assumes the provided YAML is trusted; it does not perform deep validation beyond writing the file and invoking
docker-compose
. - Ensure the MCP host has
docker-compose
installed and the user running the MCP process has permission to access the Docker socket or remote daemon. - If you need credentialed image pulls or private registries, pull images ahead of time using the
pull_image
tool or configure credentials on the target Docker host.
Testing
See ci.md
Usage
- Start the MCP server:
npm start
-
Connect to the server using any MCP client (e.g. VS Code with GitHub Copilot)
-
Use the available tools to manage your Docker services
Docker image
You can also pull a prebuilt image from GitHub Container Registry:
docker pull ghcr.io/florentb974/docker-mcp:latest
Run via MCP JSON using docker
instead of node
(Experimental)
If you prefer to start the MCP server as a Docker container from your editor (for example, using an mcp.json
provider that launches a process), you can configure it to call the docker
command directly instead of node
.
Example mcp.json
server entry (uses docker run
):
{
"servers": {
"docker-agent": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"DOCKER_SERVERS",
"ghcr.io/florentb974/docker-mcp:latest"
],
"env": {
"DOCKER_SERVERS": "local:socket:/var/run/docker.sock,remote:192.168.1.14:2735:http"
}
}
}
}
This will run the docker-mcp
container and forward its stdio to your editor. The DOCKER_SERVERS
environment variable is passed into the container so you can configure which Docker endpoints the agent should connect to. Adjust the image name and environment values as needed.