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: ```bash git clone https://github.com/yourusername/docker_mcp_server.git cd docker_mcp_server ``` 2. Create a virtual environment: ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install required packages: ```bash pip install -r requirements.txt ``` ## Usage ### Running the MCP Inspector To test and explore the server's functionality: ```bash 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 ```python # 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 ```python # 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 ```python # 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: ```bash 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](LICENSE) ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.