Docker Build and Deployment Guide (mcpo project)

What is mcpo?

mcpo (Model Context Protocol OpenAPI Proxy) is a containerized deployment using Docker and Docker Compose. It dynamically installs MCP server tools (Python uvx, Node.js npx) at startup based on a config.json, runs as a non-root user for security, and supports flexible pip and apt mirror configuration.

How to use mcpo?

Create a .env file with MCPO_API_KEY (required) and optionally PIP_SOURCE. Prepare a config.json with MCP server definitions. Build the image with docker-compose build [--no-cache] and start the service with docker-compose up -d. The container’s start.sh script installs dependencies and launches the mcpo service.

Key features of mcpo

• Dynamic dependency installation at container startup.
• Non-root user (appuser) execution for security.
• Persistent volumes for config, logs, data, and caches.
• Configurable pip source via PIP_SOURCE build argument.
• Environment isolation per MCP tool installation.

Use cases of mcpo

• Deploying mcpo with multiple MCP servers in a containerized environment.
• Replicating deployments with pinned tool versions for reproducibility.
• Running mcpo with custom pip mirrors to speed up builds.
• Managing API keys securely via .env files.

FAQ from mcpo

Why do I see “npx: command not found” or “git: command not found”?

Ensure the Dockerfile installs nodejs and git, and that the PATH includes /usr/bin. Rebuild the image with docker-compose build --no-cache.

Why do I get “mkdir: cannot create directory '/root': Permission denied”?

The container runs as non-root user appuser. All cache directories are redirected to /app via ENV variables, and start.sh only creates directories under /app.

Why is pip not using my custom PIP_SOURCE?

Confirm the .env file contains PIP_SOURCE and that docker-compose.yml passes it as a build argument (build.args). The Dockerfile must receive it via ARG PIP_SOURCE.

Why are network and dependency installations slow or failing?

The Dockerfile uses an Aliyun mirror to accelerate apt. For Python packages, set PIP_SOURCE in .env to a domestic mirror. Node.js and uv installations still depend on network availability.