Docker MCP Server

Docker MCP Server

A powerful Model Context Protocol (MCP) server that executes code in isolated Docker containers and returns the results to language models like Claude.

Features

• Isolated Code Execution: Run code in Docker containers separated from your main system
• Multi-language Support: Execute code in any language with a Docker image
• Complex Script Support: Run both simple commands and complete multi-line scripts
• Package Management: Install dependencies using pip, npm, apt-get, or apk
• Container Management: Create, list, and clean up Docker containers easily
• Robust Error Handling: Graceful timeout management and fallback mechanisms
• Colorful Output: Clear, color-coded console feedback

Requirements

• Python 3.9+
• Docker installed and running
• fastmcp library

Installation

1. Clone this repository:

   git clone https://github.com/zaycruz/docker_mcp.git
   cd docker_mcp
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install required packages:

   pip install -r requirements.txt
   

Usage

Running the MCP Inspector

To test and explore the server's functionality:

python run_server.py

The MCP Inspector interface will open in your browser at http://localhost:5173.

Available Tools

The Docker MCP server provides the following tools:

1. List Containers

Lists all Docker containers and their details:

• Parameters:
  • show_all: (Optional) Whether to show all containers including stopped ones (default: True)

2. Create Container

Creates and starts a Docker container with optional dependencies:

• Parameters:
  • image: The Docker image to use (e.g., "python:3.9-slim", "node:16")
  • container_name: A unique name for the container
  • dependencies: (Optional) Space-separated list of packages to install (e.g., "numpy pandas", "express lodash")

3. Add Dependencies

Installs additional packages in an existing Docker container:

• Parameters:
  • container_name: The name of the target container
  • dependencies: Space-separated list of packages to install

4. Execute Code

Executes a command inside a running Docker container:

• Parameters:
  • container_name: The name of the target container
  • command: The command to execute inside the container

5. Execute Python Script

Executes a multi-line Python script inside a running Docker container:

• Parameters:
  • container_name: The name of the target container
  • script_content: The full Python script content
  • script_args: Optional arguments to pass to the script

6. Cleanup Container

Stops and removes a Docker container:

• Parameters:
  • container_name: The name of the container to clean up

Examples

Basic Workflow Example

# 1. List existing containers to see what's already running
list_containers()

# 2. Create a new container
create_container(
    image="python:3.9-slim", 
    container_name="python-example", 
    dependencies="numpy pandas"
)

# 3. Execute a command in the container
execute_code(
    container_name="python-example", 
    command="python -c 'import numpy as np; print(\"NumPy version:\", np.__version__)'"
)

# 4. Add more dependencies later
add_dependencies(
    container_name="python-example", 
    dependencies="matplotlib scikit-learn"
)

# 5. List containers again to confirm status
list_containers(show_all=False)  # Only show running containers

# 6. Clean up when done
cleanup_container(container_name="python-example")

Python Data Analysis Example

# 1. Create a container with dependencies
create_container(
    image="python:3.9-slim", 
    container_name="python-test", 
    dependencies="numpy pandas matplotlib"
)

# 2. Execute a Python script
script = """
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

# Create some data
data = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100)
})

print(f"Data shape: {data.shape}")
print(f"Data correlation: {data.corr().iloc[0,1]:.4f}")
"""
execute_python_script(container_name="python-test", script_content=script)

# 3. Add additional dependencies later if needed
add_dependencies(container_name="python-test", dependencies="scikit-learn")

# 4. Verify container is running
list_containers(show_all=False)

# 5. Clean up when done
cleanup_container(container_name="python-test")

Node.js Example

# 1. Check for existing Node.js containers
list_containers()

# 2. Create a Node.js container
create_container(
    image="node:16", 
    container_name="node-test", 
    dependencies="express axios"
)

# 3. Execute a Node.js script
execute_code(
    container_name="node-test", 
    command="node -e \"console.log('Node.js version: ' + process.version); console.log('Express installed: ' + require.resolve('express'));\""
)

# 4. Add more dependencies
add_dependencies(container_name="node-test", dependencies="lodash moment")

# 5. Clean up when done
cleanup_container(container_name="node-test")

Package Manager Support

The Docker MCP server automatically detects and uses the appropriate package manager:

• Python containers: Uses pip
• Node.js containers: Uses npm
• Debian/Ubuntu containers: Uses apt-get
• Alpine containers: Uses apk

For containers where the package manager isn't obvious from the image name, the server attempts to detect available package managers.

Integrating with Claude and Other LLMs

This MCP server can be integrated with Claude and other LLMs that support the Model Context Protocol. Use the fastmcp install command to register it with Claude:

fastmcp install src/docker_mcp.py

Troubleshooting

• Port Already in Use: If you see "Address already in use" errors, ensure no other MCP Inspector instances are running.
• Docker Connection Issues: Verify that Docker is running with docker --version.
• Container Timeouts: The server includes fallback mechanisms for containers that don't respond within expected timeframes.
• Package Installation Failures: Check that the package name is correct for the specified package manager.
• No Containers Found: If list_containers shows no results, Docker might not have any containers created yet.

Security Considerations

This server executes code in Docker containers, which provides isolation from the host system. However, exercise caution:

• Don't expose this server publicly without additional security measures
• Be careful when mounting host volumes into containers
• Consider resource limits for containers to prevent DoS attacks

License

MIT License

Contributing

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