Labsco
afstanton logo

Docker MCP

★ 1

from afstanton

A Ruby implementation of an MCP server for managing and using Docker

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#devops#git#security

DockerMCP

A Model Context Protocol (MCP) server that provides comprehensive Docker management capabilities through a standardized interface. This tool enables AI assistants and other MCP clients to interact with Docker containers, images, networks, and volumes programmatically.

⚠️ Security Warning

This tool is inherently unsafe and should be used with extreme caution.

  • Arbitrary Code Execution: The exec_container tool allows execution of arbitrary commands inside Docker containers
  • File System Access: The copy_to_container tool can copy files from the host system into containers
  • Container Management: Full container lifecycle management including creation, modification, and deletion
  • Network & Volume Control: Complete control over Docker networks and volumes

Recommendations:

  • Only use in trusted environments
  • Ensure proper Docker daemon security configuration
  • Consider running with restricted Docker permissions
  • Monitor and audit all container operations
  • Be cautious when exposing this tool to external or untrusted MCP clients

🔨 Tools

This MCP server provides 22 comprehensive Docker management tools organized by functionality:

Container Management

  • list_containers - List all Docker containers (running and stopped) with detailed information
  • create_container - Create a new container from an image without starting it
  • run_container - Create and immediately start a container from an image
  • start_container - Start an existing stopped container
  • stop_container - Stop a running container gracefully
  • remove_container - Delete a container (must be stopped first unless forced)
  • recreate_container - Stop, remove, and recreate a container with the same configuration
  • exec_container ⚠️ - Execute arbitrary commands inside a running container
  • fetch_container_logs - Retrieve stdout/stderr logs from a container
  • copy_to_container ⚠️ - Copy files or directories from host to container

Image Management

  • list_images - List all Docker images available locally
  • pull_image - Download an image from a Docker registry
  • push_image - Upload an image to a Docker registry
  • build_image - Build a new image from a Dockerfile
  • tag_image - Create a new tag for an existing image
  • remove_image - Delete an image from local storage

Network Management

  • list_networks - List all Docker networks
  • create_network - Create a new Docker network
  • remove_network - Delete a Docker network

Volume Management

  • list_volumes - List all Docker volumes
  • create_volume - Create a new Docker volume for persistent data
  • remove_volume - Delete a Docker volume

Tool Parameters

Most tools accept standard Docker parameters:

  • Container ID/Name: Can use either the full container ID, short ID, or container name
  • Image: Specify images using name:tag format (e.g., nginx:latest, ubuntu:22.04)
  • Ports: Use Docker port mapping syntax (e.g., "8080:80")
  • Volumes: Use Docker volume mount syntax (e.g., "/host/path:/container/path")
  • Environment: Set environment variables as KEY=VALUE pairs

Common Use Cases

Development Environment Setup

# Pull development image
pull_image from_image="node:18-alpine"

# Create development container with volume mounts
run_container image="node:18-alpine" name="dev-env" \
  host_config='{"PortBindings":{"3000/tcp":[{"HostPort":"3000"}]},"Binds":["/local/project:/app"]}'

# Execute development commands
exec_container id="dev-env" cmd="npm install"
exec_container id="dev-env" cmd="npm start"

Container Debugging

# Check container status
list_containers

# View container logs
fetch_container_logs id="problematic-container"

# Execute diagnostic commands
exec_container id="problematic-container" cmd="ps aux"
exec_container id="problematic-container" cmd="df -h"
exec_container id="problematic-container" cmd="netstat -tlnp"

File Management

# Copy configuration files to container
copy_to_container id="web-server" \
  source_path="/local/nginx.conf" \
  destination_path="/etc/nginx/"

# Copy application code
copy_to_container id="app-container" \
  source_path="/local/src" \
  destination_path="/app/"

Error Handling

The server provides detailed error messages for common issues:

  • Container Not Found: When referencing non-existent containers
  • Image Not Available: When trying to use images that aren't pulled locally
  • Permission Denied: When Docker daemon access is restricted
  • Network Conflicts: When creating networks with conflicting configurations
  • Volume Mount Issues: When specified paths don't exist or lack permissions

All errors include descriptive messages to help diagnose and resolve issues.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Running Tests

# Install dependencies
bundle install

# Run the test suite
bundle exec rake spec

# Run tests with coverage
bundle exec rake spec COVERAGE=true

Local Development Setup

# Clone the repository
git clone https://github.com/afstanton/docker_mcp.git
cd docker_mcp

# Install dependencies
bin/setup

# Start development console
bin/console

# Build the gem locally
bundle exec rake build

# Install locally built gem
bundle exec rake install

Testing with MCP Client

# Start the MCP server locally
bundle exec exe/docker_mcp

# Configure your MCP client to use local development server
# Use file path instead of installed gem command

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.