An example Docker image for mcpo(with npm,curl,nodejs,uv Pre-Built;Pre-Built MCP:amap;baidumap;server-brave-search; tavily;fetch), a tool that exposes MCP (Model Context Protocol) servers as OpenAPI-compatible HTTP endpoints for OpenWebUI.
Thanks to @BigUncle for the pull request
This guide systematically outlines the build, deployment, troubleshooting, and best practices for the mcpo project in Docker container environments, reflecting the project's current state.
This project uses Docker and Docker Compose for containerized deployment of mcpo
(Model Context Protocol OpenAPI Proxy). Core design principles include:
start.sh
script reads config.json
and dynamically installs required Python (uvx
) and Node.js (npx
) tools based on defined mcpServers
.appuser
to enhance security.uv
and npm
are persisted to the host machine.pip
sources via build argument (PIP_SOURCE
), and uses Aliyun mirror by default to accelerate apt
.start.sh
, each MCP tool installation occurs in a sub-shell to avoid environment variable conflicts.Docker & Docker Compose: Docker 24+ and Docker Compose 2.x recommended.
.env
File: Create an .env
file in the project root directory for sensitive information and configuration. Include MCPO_API_KEY
. Refer to .env.example
.
# .env file example
# pip source used during Docker build (optional, uses default source if empty)
PIP_SOURCE=https://mirrors.aliyun.com/pypi/simple/
# API Key required for mcpo runtime (required)
MCPO_API_KEY=your_mcpo_api_key_here
# Other API Keys that may be needed for mcp servers (according to config.json)
# AMAP_MAPS_API_KEY=your_amap_key
# ... other required environment variables
config.json
: Configure MCP servers to start. Refer to config.example.json
.
Network: Ensure access to Debian (Aliyun mirror), NodeSource, PyPI (or specified PIP_SOURCE
).
Dockerfile
: Defines image build process.
python:3.13-slim
bash
, curl
, jq
, nodejs
(v22.x), git
, uv
(via pip)appuser
.PIP_SOURCE
build argument.start.sh
: Container entrypoint script.
HOME
, UV_CACHE_DIR
, NPM_CONFIG_CACHE
.config.json
and dynamically installs MCP tools (using uvx
or npx
).mcpo
main service.docker-compose.yml
: Defines services, build parameters, volume mounts, environment variables.
PIP_SOURCE
to Dockerfile../config.json
, ./logs
, ./data
, ./node_modules
, ./.npm
, ./.uv_cache
..env
as runtime environment variables via env_file
.readme-docker.md
: This document.test_mcp_tools.sh
: Basic functionality test script.# Pass PIP_SOURCE (compose will automatically read from .env if defined)
docker-compose build [--no-cache]
--no-cache
: Forces rebuild of all layers to ensure latest changes take effect.PIP_SOURCE
from .env
file (if valid) to configure pip
source.# Start service (run in background)
docker-compose up -d
docker-compose.yml
loads variables from .env
as container runtime environment variables.start.sh
executes, dynamically installing MCP tools defined in config.json
.mcpo
main service starts.npx: command not found
/ git: command not found
npx
(installed with nodejs
) or git
not installed or their paths not in appuser
's PATH
environment variable.Dockerfile
's apt-get install
includes nodejs
and git
.ENV PATH
directive includes /usr/bin
(where apt
-installed nodejs
and git
typically reside). Dockerfile already includes /app/.local/bin:/usr/bin:/usr/local/bin:$PATH
.docker-compose build --no-cache
to rebuild.mkdir: cannot create directory '/root': Permission denied
appuser
, but scripts or dependencies attempt to write to /root
directory (e.g., default cache paths).uv
, npm
) redirected to /app
via ENV
directives (UV_CACHE_DIR
, NPM_CONFIG_CACHE
, HOME
).mkdir -p
in start.sh
only operates on directories under /app
.docker-compose.yml
updated to /app/...
.pip
not using custom source (PIP_SOURCE
)PIP_SOURCE
not correctly passed to Dockerfile during build..env
file contains PIP_SOURCE=https://...
.docker-compose.yml
's build.args
section includes - PIP_SOURCE=${PIP_SOURCE:-}
.ARG PIP_SOURCE
and uses via export PIP_INDEX_URL
in RUN
layers.apt
.pip
can be configured with domestic mirrors via PIP_SOURCE
in .env
.appuser
.config.json
, logs
, data
, node_modules
, .npm
, .uv_cache
to preserve state and dependencies..env
file, inject via env_file
, never COPY
.env
into the image or hardcode keys. .env
file should be in .gitignore
.start.sh
's dynamic installation mechanism provides flexibility, but means longer startup time on first launch or after config.json
changes.uv
version in Dockerfile
(pip install --user uv==X.Y.Z
) and npx
package versions in config.json
(@amap/[email protected]
).docker-compose.yml
../logs
directory for easy viewing and management.test_mcp_tools.sh
script for basic functionality verification.docker-compose build [--no-cache]
docker-compose up -d
No configuration available
Related projects feature coming soon
Will recommend related projects based on sub-categories