Installation

Runtime prerequisites

Installing the mcpd binary is separate from installing MCP server runtimes. After installation, install only the runtime(s) your servers use: uv for uvx::..., npx for npx::..., and Docker for docker::.... See Requirements for details.

via Homebrew

Add the Mozilla.ai tap:

brew tap mozilla-ai/tap

Then install mcpd:

brew install mcpd

Or install directly from the cask:

brew install --cask mozilla-ai/tap/mcpd

via GitHub releases

Official releases can be found on the mcpd GitHub releases page.

The following is an example of manually downloading and installing mcpd using curl and jq by running install_mcpd:

function install_mcpd() {
    command -v curl >/dev/null || { echo "curl not found"; return 1; }
    command -v jq >/dev/null || { echo "jq not found"; return 1; }

    latest_version=$(curl -s https://api.github.com/repos/mozilla-ai/mcpd/releases/latest | jq -r .tag_name)
    os=$(uname)
    arch=$(uname -m)

    zip_name="mcpd_${os}_${arch}.tar.gz"
    url="https://github.com/mozilla-ai/mcpd/releases/download/${latest_version}/${zip_name}"

    echo "Downloading: $url"
    curl -sSL "$url" -o "$zip_name" || { echo "Download failed"; return 1; }

    echo "Extracting: $zip_name"
    tar -xzf "$zip_name" mcpd || { echo "Extraction failed"; return 1; }

    echo "Installing to /usr/local/bin"
    sudo mv mcpd /usr/local/bin/mcpd && sudo chmod +x /usr/local/bin/mcpd || { echo "Install failed"; return 1; }

    rm -f "$zip_name"
    echo "mcpd installed successfully"
}

macOS Gatekeeper quarantine

If you're on macOS, remove the quarantine flag before running mcpd:

xattr -d com.apple.quarantine mcpd

via local Go binary build

# Clone the Git repo
git clone [e-mail]:mozilla-ai/mcpd.git
cd mcpd
# Checkout a specific tag (or build latest main)
git fetch --tags
git checkout v0.4.0
# Use Makefile commands to build and install mcpd
make build
sudo make install # Installs mcpd 'globally' to /usr/local/bin

Run with Docker

mcpd is available as the Docker image mzdotai/mcpd.

Dockerfile environment variables

The Dockerfile defines sensible defaults for configuration via environment variables. These can be overridden at runtime using docker run -e KEY=VALUE.

Default environment variables

Name	Default Value
MCPD_API_PORT	8090
MCPD_LOG_LEVEL	info
MCPD_LOG_PATH	/var/log/mcpd/mcpd.log
MCPD_CONFIG_FILE	/etc/mcpd/.mcpd.toml
MCPD_RUNTIME_FILE	/home/mcpd/.config/mcpd/secrets.prod.toml

To run mcpd with Docker, map the required port and bind mount your .mcpd.toml configuration file and runtime secrets file:

docker run  -p 8090:8090 \
            -v $PWD/.mcpd.toml:/etc/mcpd/.mcpd.toml \
            -v $HOME/.config/mcpd/secrets.dev.toml:/home/mcpd/.config/mcpd/secrets.prod.toml \
            -e MCPD_LOG_LEVEL=debug \
            mzdotai/mcpd:v0.4.0

Mounting plugin binaries

If you have [plugins] configured, bind mount the plugin directory as well and point [plugins].dir at the in-container path:

docker run  -p 8090:8090 \
            -v $PWD/.mcpd.toml:/etc/mcpd/.mcpd.toml \
            -v $PWD/plugins:/etc/mcpd/plugins:ro \
            -v $HOME/.config/mcpd/secrets.dev.toml:/home/mcpd/.config/mcpd/secrets.prod.toml \
            mzdotai/mcpd:v0.4.0

Plugins must match the container, not the host

Plugin binaries are executed inside the container, so they must be built for the image's OS, architecture and C library — the published image is multi-arch (linux/amd64 and linux/arm64) and Alpine-based (musl). Build for the architecture Docker pulled for your host, not for your host's toolchain default; a mismatch fails with exec format error. See Plugin Configuration.

Running Docker-based MCP servers from containerized mcpd

If your MCP servers use the Docker runtime, mount the host's Docker socket to allow mcpd to manage containers on the host:

docker run  -p 8090:8090 \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v $PWD/.mcpd.toml:/etc/mcpd/.mcpd.toml \
            -v $HOME/.config/mcpd/secrets.dev.toml:/home/mcpd/.config/mcpd/secrets.prod.toml \
            -e MCPD_LOG_LEVEL=debug \
            mzdotai/mcpd:v0.4.0

Security Note

Mounting the Docker socket grants the container full access to the host's Docker daemon. Only use this with trusted images.

If Docker-based MCP servers do not work when mcpd itself is running in Docker, see Troubleshooting.

CI/CD Deployment (GitHub Actions)

For automated deployments, a reference GitHub Actions workflow is available in the repository that demonstrates:

• Version-pinned deployments using release tags
• Secret resolution from GitHub Secrets into a .env file for Docker
• Configuration validation

See the following files:

• .github/workflows/deploy.yaml - Example workflow
• scripts/resolve-secrets.sh - Resolves MCPD__ prefixed secrets

Use mcpd config export to generate the portable execution context required for deployment.