Docker Executor MCP server

The Docker MCP Server provides a secure way to execute code in isolated Docker containers and return results to language models like Claude. It supports multiple languages, complex scripts, package management, and container management with robust error handling.

Requirements

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

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/docker_mcp_server.git
   cd docker_mcp_server
   

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

List Containers

Lists all Docker containers and their details:

list_containers(show_all=True)  # show_all is optional, defaults to True

Create Container

Creates and starts a Docker container with optional dependencies:

create_container(
    image="python:3.9-slim", 
    container_name="python-example", 
    dependencies="numpy pandas"  # optional
)

Add Dependencies

Installs additional packages in an existing Docker container:

add_dependencies(
    container_name="python-example", 
    dependencies="matplotlib scikit-learn"
)

Execute Code

Executes a command inside a running Docker container:

execute_code(
    container_name="python-example", 
    command="python -c 'import numpy as np; print(\"NumPy version:\", np.__version__)'"
)

Execute Python Script

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

execute_python_script(
    container_name="python-example", 
    script_content="your_python_code_here", 
    script_args=""  # optional
)

Cleanup Container

Stops and removes a Docker container:

cleanup_container(container_name="python-example")

Example Workflows

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

Integrating with Claude and Other LLMs

To register the MCP server with Claude:

fastmcp install src/docker_mcp.py

Troubleshooting

• Port Already in Use: Ensure no other MCP Inspector instances are running
• Docker Connection Issues: Verify Docker is running with docker --version
• Container Timeouts: The server includes fallback mechanisms for unresponsive containers
• Package Installation Failures: Check that package names are correct
• No Containers Found: Docker might not have any containers created yet

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "docker-mcp" '{"command":"python","args":["run_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "docker-mcp": {
            "command": "python",
            "args": [
                "run_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "docker-mcp": {
            "command": "python",
            "args": [
                "run_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect