Docker MCP Server

This module provides an implementation of a Model Context Protocol MCP server for Docker commands, powered by the mcp_mediator core framework. The Docker MCP Server utilizes the automatic server generation feature of MCP Mediator to expose existing Docker commands as MCP Tools. Each command is optionally annotated with @McpTool along with a minimal description to enhance tool discoverability and usability.

👉 See the full list of supported commands here.

Usage Examples

java -jar docker-mcp-server.jar \
  --docker-host=tcp://localhost:2376 \
  --tls-verify \
  --cert-path=/etc/docker/certs \
  --server-name=my-server \
  --server-version=1.0.0 \
  --max-connections=150 \
  --docker-config=/custom/docker/config

To run Docker MCP Server with Claude Desktop with java -jar:

{
  "mcpServers": {
    "my_java_mcp_server": {
      "command": "java",
      "args": [
        "-jar",
        "docker-mcp-server.jar"
        "--docker-host=tcp://localhost:2376",
        "--tls-verify", # not required
        "--cert-path=/etc/docker/certs", # required only if --tls-verify is available
        "--server-name=my-docker-mcp-server",
        "--server-version=1.0.0",
        "--max-connections=150",
        "--docker-config=/custom/docker/config"
      ]
    }
  }
}

Or create the native image (see the steps below) and use the standalone application:

{
  "mcpServers": {
    "my_java_mcp_server": {
      "command": "docker-mcp-server-executable",
      "args": [
        "--docker-host=tcp://localhost:2376" // rest of args
      ]
    }
  }
}

How to Build

To build the executable:

mvn clean compile package

This command creates a jar file under target folder mcp-mediator-implementation-docker-[version].jar. You can stop here and use the jar file and execute it using java -jar command. Or, you can create a standalone executable application using GraalVM native image:

 native-image -jar mcp-mediator-implementation-docker-[version].jar     

and this command creates an executable file: 'mcp-mediator-implementation-docker-[version] that can be executed.

Automatically Generate MCP Tools

This project integrates with MCP Mediator to automatically generate MCP Tools from existing Docker services.

Each method in the Docker service class can optionally be annotated with @McpTool to explicitly define the tool’s * name*, description, and other metadata.

However, annotation is not required—MCP Mediator supports automatic generation for non-annotated methods by inferring details from the method, class, and package names. To enable this behavior, set createForNonAnnotatedMethods to true:

DefaultMcpMediator mediator = new DefaultMcpMediator(McpMediatorConfigurationBuilder.builder()
        .createDefault()
        .serverName(serverName)
        .serverVersion(serverVersion)
        .build());

mediator.

registerHandler(McpServiceFactory.create(dockerClientService)
        .

createForNonAnnotatedMethods(true)); // Enables support for non-annotated methods

Check io.github.makbn.mcp.mediator.docker.server.DockerMcpServer for the full Mcp Mediator configuration.

Supported CLI Options

Option	Description	Default
--docker-host	Docker daemon host URI	unix:///var/run/docker.sock
--tls-verify	Enable TLS verification (used with --cert-path)	false
--cert-path	Path to Docker TLS client certificates (required if TLS is enabled)	none
--docker-config	Custom Docker config directory	~/.docker
--server-name	Server name for the MCP server	docker_mcp_server
--server-version	Server version label	1.0.0.0
--max-connections	Maximum number of connections to Docker daemon	100
--help	Show usage and available options	n/a

Environment variables:

Option	Description	Default
DOCKER_MCP_LOG_LEVEL	Logging level (TRACE, DEBUG, INFO, etc.)	DEBUG
DOCKER_MCP_LOG_FILE	Path to log output file	logs/docker_mcp_server.log

Supported Docker Commands as MCP Server Tools

MCP Tool Name	Description
docker_start_container	Start a Docker container by ID.
docker_stop_container	Stop a Docker container by ID.
docker_leave_swarm	Remove a node from Docker Swarm.
docker_container_diff	Show changes made to a container’s filesystem.
docker_build_image_file	Build an image from Dockerfile or directory.
docker_inspect_volume	Get details of a Docker volume.
docker_remove_service	Remove a Docker service by ID.
docker_list_containers	List containers with optional filters.
docker_inspect_swarm	Inspect Docker Swarm details.
docker_push_image	Push image to registry, supports auth.
docker_copy_archive_to_container	Copy a tar archive into a running container.
docker_stats_container	Fetch container stats (CPU, memory, etc.).
docker_disconnect_container_from_network	Disconnect container from Docker network.
docker_remove_container	Remove a container, with optional force.
docker_inspect_service	Inspect a Docker service.
docker_remove_secret	Remove a Docker secret by ID.
docker_pull_image	Pull image from registry, supports auth.
docker_inspect_container	Inspect container config and state.
docker_unpause_container	Unpause a paused container.
docker_list_images	List Docker images with optional filters.
docker_list_services	List all Docker services in the swarm.
docker_remove_image	Remove an image, with force and prune options.
docker_create_network	Create a Docker network.
docker_tag_image	Tag an image with a new repo and tag.
docker_authenticate	Authenticate to Docker registry.
docker_exec_command	Execute a command inside a container.
docker_remove_swarm_node	Remove a swarm node, optionally forcibly.
docker_search_images	Search Docker Hub for images.
docker_list_networks	List all Docker networks.
docker_remove_volume	Remove a Docker volume.
docker_create_container	Create a container with custom settings.
docker_remove_network	Remove a Docker network.
docker_copy_archive_from_container	Copy files from a container to the host.
docker_rename_container	Rename a Docker container.
docker_pause_container	Pause a running container.
docker_version	Get Docker version information.
docker_list_swarm_nodes	List all nodes in the Docker swarm.
docker_log_container	Retrieve logs from a container.
docker_prune	Prune unused Docker resources.
docker_inspect_network	Get detailed info about a network.
docker_kill_container	Send a kill signal to a container.
docker_top_container	Get running processes in a container.
docker_list_volumes	List Docker volumes with optional filters.
docker_update_swarm_node	Update the config of a swarm node.
docker_info	Show Docker system-wide info.
docker_log_service	Get logs from a Docker service.
docker_load_image	Load an image from a tar archive.
docker_list_tasks	Lists the tasks in a Docker Swarm environment.
docker_save_image	Saves a Docker image to a local tar file.
docker_join_swarm	Joins the node to an existing Swarm cluster.
docker_create_volume	Creates a new Docker volume.
docker_initialize_swarm	Initializes a new Docker Swarm cluster.

Work in progress, more to be added.

DockerClientService Function Coverage

Check the DockerClientService class for the full list of available and planned tools (to be implemented)

🧩 Repository Structure and Git Subtree Setup

This project is a Git subtree module of the parent repository makbn/mcp_mediator. It is kept in its own repository to support independent versioning, CI, and release processes, while remaining integrated into the main mcp_mediator mono-repo.

🔀 Cloning Structure

If you're working in the context of the full mcp_mediator system:

`git clone --recurse-submodules https://github.com/makbn/docker_mcp_server.git`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Read this first!

License

This project is licensed under the GPL3 License—see the LICENSE file for details.