docker-mcp

leejoker/docker-mcp

3.3

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 dayong@mcphub.com.

Docker-MCP is a Ruby-based server that provides Model Context Protocol (MCP) tools for interacting with Docker services.

Tools
10
Resources
0
Prompts
0

Docker-MCP

Docker-MCP is a Ruby-based server that provides Model Context Protocol (MCP) tools for interacting with Docker services. It allows external clients to perform Docker operations such as managing images, containers, and getting Docker service information through a standardized MCP interface.

阅读此文档的其他语言版本:

🚀 Features

  • Docker Operations: Manage Docker images and containers remotely
  • Service Information: Get Docker service version and system information
  • MCP Standard: Implements the Model Context Protocol for standardized interactions
  • Container Ready: Dockerfile and docker-compose configuration included
  • Stdio Interface: Communicates via standard input/output streams
  • Container Creation: Create and manage containers with configurable ports
  • Image Management: Pull, list, and remove Docker images
  • Container Management: List, inspect, and create Docker containers

📋 Prerequisites

  • Ruby 3.4+
  • Docker API access (ensure Docker daemon is running)
  • Node.js (for supergateway dependency)

🛠️ Installation

Local Installation

  1. Clone the repository:

    git clone https://github.com/leejoker/docker-mcp.git
cd docker-mcp

  2. Install dependencies:

    gem install bundler # if not already installed
bundle install

  3. Install supergateway (for HTTP interface):

    npm install -g supergateway

  4. Run the server directly:

    ./bin/docker-mcp

    Or use supergateway to expose as HTTP:

    supergateway --stdio "./bin/docker-mcp" --port 8080 --baseUrl "http://localhost:8080" --ssePath "/sse" --messagePath "/message"

Using Docker

Build and run the service using Docker:

# Build the image
docker build -t docker-mcp:1.0.0 .

# Run the container
docker run -d --name docker-mcp -p 8080:8080 --restart unless-stopped docker-mcp:1.0.0

Or use the provided docker-compose file (note: you may need to update it to include the Docker socket mount for full functionality):

docker-compose up -d

Important: To ensure Docker-MCP can communicate with your Docker daemon, you'll likely need to add the Docker socket volume mount to your docker-compose.yaml file:

version: '3'

services:
  docker-mcp:
    image: docker-mcp:1.0.0
    container_name: docker-mcp
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Required for Docker API access
    restart: unless-stopped

⚙️ Dependencies

This project relies on the following key dependencies:

  • docker-api gem: Provides Ruby interface to communicate with Docker daemon
  • fast-mcp gem: Implements the Model Context Protocol standard
  • supergateway: Allows stdio-to-HTTP communication for MCP interaction (runtime dependency when using HTTP interface)
  • timbru31/ruby-node:3.4-slim-iron: Base Docker image with Ruby 3.4 and Node.js

🛠 Available Tools

The server provides the following Docker MCP tools:

Health Check

  • PingTool: Check server health status
    • Description: ping the server to check it healthy status
    • Returns: 'pong'

Docker Service Information

  • DockerVersion: Get Docker service version

    • Description: show the version of docker service
    • Returns: Docker version information

  • DockerInfo: Get Docker service information

    • Description: show the info of docker service
    • Returns: Docker system information

Image Management

  • ImageList: List all Docker images

    • Description: show all docker image info
    • Returns: JSON array of image information

  • ImagePull: Pull a Docker image by URL

    • Description: pull an docker image with specified url and then return the image info
    • Arguments: url (required string) - Docker image URL
    • Returns: Image information after pulling

  • ImageRemove: Remove an image by URL

    • Description: remove an docker image with specified url then return the image info, url format is [repo:tag]
    • Arguments: url (required string) - Docker image URL in format repo:tag
    • Returns: Information about the removed image

  • ImageRemoveById: Remove an image by ID

    • Description: remove an docker image by id
    • Arguments: id (required string) - Docker image ID
    • Returns: Information about the removed image

  • ImageSave: Save or export a Docker image to local file

    • Description: save or export an docker image to local
    • Arguments:
      • url (required string) - Docker image URL
      • file (required string) - Local file path to save the image
    • Returns: Object with the saved image path

Container Management

  • ContainerList: List all Docker containers

    • Description: show all docker containers info
    • Returns: JSON array of container information

  • ContainerInfo: Get information about a specific container

    • Description: show container info by container id
    • Arguments: id (required string) - Container ID
    • Returns: Detailed container information

  • ContainerCreate: Create a new container with image, port, and optional configurations

    • Description: create container with image name, tag, and optional configurations for volumes, tty, and stdin
    • Arguments:
      • image (required string) - Image name
      • tag (required string) - Image tag
      • port (required string) - Container port to expose
      • target_port (required string) - Host port to bind to
      • volumes (optional string) - Volume mappings in format as string separated by commas (e.g., "/host/path1:/container/path1,/host/path2:/container/path2")
      • tty (optional bool) - Allocate a pseudo-TTY (default: true)
      • open_stdin (optional bool) - Keep STDIN open even if not attached (default: true)
    • Returns: Container information after creation
    • Notes: The container is created with auto-removal enabled and configurable TTY/stdin options and volume mappings

🏗️ Architecture

The project is structured as follows:

lib/
├── server/
│   └── stdio_server.rb    # Main MCP server implementation
└── tools/
    ├── hello.rb          # Health check tool
    ├── docker.rb         # Docker service information tools
    ├── image.rb          # Image management tools
    └── container.rb      # Container management tools

Core Components

  • StdioServer: The main server class that dynamically discovers and registers all MCP tools, then starts the server
  • PingTool: Simple health check functionality
  • DockerTools: Namespace containing all Docker-related tools
  • DockerVersion & DockerInfo: Service information tools
  • Image Tools: Image listing, pulling, and removal tools
  • Container Tools: Container listing, inspection, and creation tools

🧪 Usage Examples

Using with an MCP client

Once the server is running, you can interact with it using an MCP client. Here are example calls:

  • PingTool: Check server status

    {
  "method": "call_tool",
  "params": {
    "name": "ping_tool",
    "arguments": {}
  }
}

  • DockerVersion: Get Docker version

    {
  "method": "call_tool",
  "params": {
    "name": "docker_version",
    "arguments": {}
  }
}

  • ImageList: List all images

    {
  "method": "call_tool",
  "params": {
    "name": "image_list",
    "arguments": {}
  }
}

  • ImagePull: Pull a specific image

    {
  "method": "call_tool",
  "params": {
    "name": "image_pull",
    "arguments": {
      "url": "nginx:latest"
    }
  }
}

  • ImageSave: Save a Docker image to a local file

    {
  "method": "call_tool",
  "params": {
    "name": "image_save",
    "arguments": {
      "url": "nginx:latest",
      "file": "/tmp/nginx.tar"
    }
  }
}

  • ContainerCreate: Create a new container

    {
  "method": "call_tool",
  "params": {
    "name": "container_create",
    "arguments": {
      "image": "nginx",
      "tag": "latest",
      "port": "80",
      "target_port": "8080"
    }
  }
}

  • ContainerCreate with volume mapping and custom options:

    {
  "method": "call_tool",
  "params": {
    "name": "container_create",
    "arguments": {
      "image": "nginx",
      "tag": "latest",
      "port": "80",
      "target_port": "8080",
      "volumes": "/host/data:/usr/share/nginx/html",
      "tty": true,
      "open_stdin": true
    }
  }
}

🚀 Development

To run the server locally for development:

  1. Install dependencies:

    bundle install
npm install -g supergateway

  2. Run the server directly:

    ./bin/docker-mcp

    Or use supergateway to expose as HTTP:

    supergateway --stdio "./bin/docker-mcp" --port 8080 --baseUrl "http://localhost:8080" --ssePath "/sse" --messagePath "/message"

This will start the stdio server which can be connected to via supergateway for HTTP access.

🧪 Testing

To run the project tests (if any exist):

bundle exec rake test
# or
rspec

🔐 Docker Access Configuration

For Docker API access, ensure the Docker daemon is running and accessible. You must mount the Docker socket to allow the container to communicate with the host Docker daemon:

# When running Docker container directly
docker run -d --name docker-mcp -p 8080:8080 --restart unless-stopped -v /var/run/docker.sock:/var/run/docker.sock docker-mcp:1.0.0

Or update your docker-compose.yaml with the required volume mount:

version: '3'

services:
  docker-mcp:
    image: docker-mcp:1.0.0
    container_name: docker-mcp
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests if applicable
  5. Commit your changes (git commit -m 'Add some amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a pull request

📄 License

This project is licensed under the Apache License 2.0 - see the file for details.

👤 Author

🙏 Acknowledgments