docker_mcp_server

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.

[!IMPORTANT]
This is part of mcp_mediator project: https://github.com/makbn/docker_mcp_server To build or modify, clone the parent repository: git clone --recurse-submodules https://github.com/makbn/docker_mcp_server.git

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

Environment variables:

Supported Docker Commands as MCP Server Tools

Work in progress, more to be added.

DockerClientService Function Coverage

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

[!IMPORTANT]
Almost all the MCP Tools' descriptions and names are generated automatically using AI agent!

🧩 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.