> For the complete documentation index, see [llms.txt](https://docs.mozilla.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozilla.ai/mcpd/installation.md).

# Installation

{% hint style="info" %}
**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](/mcpd/requirements.md) for details.
{% endhint %}

## via Homebrew

Add the Mozilla.ai tap:

```bash
brew tap mozilla-ai/tap
```

Then install `mcpd`:

```bash
brew install mcpd
```

Or install directly from the cask:

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

## via GitHub releases

Official releases can be found on the [mcpd GitHub releases page](https://github.com/mozilla-ai/mcpd/releases).

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

```bash
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"
}
```

{% hint style="info" %}
**macOS Gatekeeper quarantine**

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

```bash
xattr -d com.apple.quarantine mcpd
```

{% endhint %}

## via local Go binary build

```bash
# Clone the Git repo
git clone git@github.com: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](https://hub.docker.com/repository/docker/mzdotai/mcpd/general).

{% hint style="info" %}
**Dockerfile environment variables**

The [Dockerfile](https://github.com/mozilla-ai/mcpd/blob/main/Dockerfile) defines sensible defaults for configuration via environment variables. These can be overridden at runtime using `docker run -e KEY=VALUE`.
{% endhint %}

### 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:

```bash
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:

```bash
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
```

{% hint style="warning" %}
**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](/mcpd/configuration/plugin-configuration.md#architecture-and-libc-compatibility).
{% endhint %}

### 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:

```bash
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
```

{% hint style="warning" %}
**Security Note**

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

If Docker-based MCP servers do not work when `mcpd` itself is running in Docker, see [Troubleshooting](/mcpd/troubleshooting.md).

### 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`](https://github.com/mozilla-ai/mcpd/blob/main/.github/workflows/deploy.yaml) - Example workflow
* [`scripts/resolve-secrets.sh`](https://github.com/mozilla-ai/mcpd/blob/main/scripts/resolve-secrets.sh) - Resolves `MCPD__` prefixed secrets

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mozilla.ai/mcpd/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.