Running MCP Services with Docker via MCPO (DooD Strategy)

[zhanghao-njmu]

Running MCP Services with Docker via MCPO (DooD Strategy)

Due to limitations where some MCP services cannot be installed using uvx or npx, or for scenarios requiring more secure isolation, it's beneficial to run these services via Docker. This guide outlines an updated Docker configuration using the Docker outside of Docker (DooD) strategy. This allows all MCP services, including those running in their own Docker containers, to be managed centrally by the main mcpo instance.

The setup involves these main steps:

1. Create a New Docker Image with Docker CLI

Build a custom Docker image based on the official mcpo image, but with the Docker CLI installed. This enables the mcpo container to execute docker commands.

Dockerfile:

# Use the official mcpo image as the base
FROM ghcr.io/open-webui/mcpo:main

# Update package lists and install docker.io (which includes the Docker CLI)
RUN apt-get update && \
    apt-get install -y --no-install-recommends docker.io && \
    # Clean up apt cache to reduce image size
    rm -rf /var/lib/apt/lists/*

Build this image:

docker build -t mcpo-with-docker -f ./Dockerfile .    # or with proxy: --build-arg https_proxy=xxx

(Make sure the Dockerfile is in the current directory when running the build command)

2. Mount the Host's Docker Socket in docker-compose.yml

Modify the docker-compose.yml file to mount the host machine's Docker socket (/var/run/docker.sock) into the mcpo container. This allows the Docker CLI inside the container to communicate with the Docker daemon running on the host.

docker-compose.yml:

services:
  mcpo:
    # Use the custom image built in Step 1
    image: mcpo-with-docker
    container_name: mcpo
    restart: unless-stopped
    networks:
      - mcpo-network
    ports:
      # Expose mcpo's port (e.g., 5002 on host maps to 8000 in container)
      - '5002:8000'
    volumes:
      # Mount configuration file (read-only)
      - ./config.json:/app/config.json:ro
      # Mount persistent data for memory service
      - ./mcpo_data/memory.json:/mcpo_data/memory/memory.json
      # Mount persistent data for filesystem service
      - ./mcpo_data/filesystem:/mcpo_data/filesystem
      # --- Key Change: Mount the host's Docker socket ---
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Optional: Proxy settings if needed within the container
      - 'HTTPS_PROXY=http://172.24.0.1:10809'
      - 'https_proxy=http://172.24.0.1:10809'
      - 'NO_PROXY=localhost,127.0.0.1,.mcpo-network'
      - 'no_proxy=localhost,127.0.0.1,.mcpo-network'
    # Command to run mcpo, including API key
    command: ["--config", "/app/config.json", "--api-key", "VLXS3pMLx588A8y82i6JeXm7MtV29uSzRmASaHHdb5cIlonmy8HLKddu"]

networks:
  mcpo-network:
    name: mcpo-network
    driver: bridge
    ipam:
      config:
        - subnet: 172.5.0.0/16 # Example custom subnet

Note: Ensure the user running the mcpo container (or the Docker daemon itself) has the necessary permissions to access /var/run/docker.sock on the host. Often, this involves adding the user to the docker group.

3. Configure Services in config.json

Update the mcpo configuration file (config.json) to define how each MCP service should be launched. For services intended to run via Docker, set the command field to "docker" and specify the Docker command arguments in the args array.

config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/mcpo_data/memory/memory.json"
      }
    },
    "time": {
      // --- Example: Run the 'time' service using Docker ---
      "command": "docker",
      "args": [
          "run",          // Docker command
          "-i",           // Keep STDIN open even if not attached
          "--rm",         // Automatically remove the container when it exits
          "--network",    // Note: Networking between mcpo and Docker-run services needs consideration.
          "mcpo-network", // They might need to be on the same Docker network
          "mcp/time:latest", // The Docker image for the time service
          "--local-timezone=Asia/Shanghai" // Arguments passed to the service inside the container
        ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem","/mcpo_data/filesystem"]
    },
    "quickchart-server": {
      "command": "npx",
      "args": ["-y","@gongrzhe/quickchart-mcp-server"]
    }
  }
}

4. Run the Setup

You have two primary ways to run this configuration:

Option A: Using Docker Compose Directly

Navigate to the directory containing your docker-compose.yml and Dockerfile (or where you built the image) and run:

docker compose up --build -d

• --build: Rebuilds the mcpo-with-docker image if the Dockerfile has changed.
• -d: Runs the containers in detached mode (in the background).

Option B: Creating a Systemd Service

For automatic startup on boot and easier management, create a systemd service file.

1. Create the service file:

   sudo vim /etc/systemd/system/mcpo.service

2. Add the following content:

   [Unit]
   Description=MCPO Service with Docker Management
   # Ensure Docker service is running before starting mcpo
   Requires=docker.service
   After=docker.service
   
   [Service]
   Type=simple
   # Set the working directory to where your docker-compose.yml is located
   WorkingDirectory=/path/to/your/mcpo/docker/setup # <-- IMPORTANT: Change this path
   # Command to start the service using docker compose
   ExecStart=/usr/bin/docker compose up --build
   # Command to stop the service
   ExecStop=/usr/bin/docker compose down
   # Disable startup timeout
   TimeoutStartSec=0
   # Restart the service if it fails
   Restart=always
   RestartSec=20s
   
   [Install]
   # Enable the service for multi-user target (standard boot)
   WantedBy=multi-user.target

   Important: Replace /path/to/your/mcpo/docker/setup with the actual path to the directory containing your docker-compose.yml, config.json, etc.

3. Enable and start the service:

   # Reload systemd to recognize the new service file
   sudo systemctl daemon-reload
   # Enable the service to start on boot
   sudo systemctl enable mcpo.service
   # Start the service immediately
   sudo systemctl start mcpo.service
   # Check the status
   sudo systemctl status mcpo.service

With this setup, your mcpo container can now launch and manage other MCP services, whether they run directly via npx/uvx within the mcpo container or are launched as separate Docker containers using the host's Docker daemon. Importantly, all MCP services managed through mcpo this way benefit from centralized control and features like automatically generated interactive documentation.

[j820301]

Hello, I also used docker compose to integrate the MCPO configuration, and the API/docs page appeared and was configured to openwebui. However, when using tools in openwebui, I encounter 401 or 404 errors. What could be the reason? I would like to ask for your experience

Here is the discussion post I made.
#110

[cristiano18222]

very nice.

[yogeeshr]

Can we host the MCPO and MCP Server as 2 separate services in cloud and connect ? any pointers?