Content
<p align="center">
<picture>
<img src="docs/assets/mcpd-logo.png" alt="mcpd" width="200"/>
</picture>
</p>
<div align="center"><b>Run your agents, not your infrastructure.</b></div>
`mcpd` is a tool to declaratively manage [Model Context Protocol](https://modelcontextprotocol.io/overview) (MCP) servers, providing a consistent interface to define and run tools across environments, from local development to containerized cloud deployments.
Built by [Mozilla AI](https://mozilla.ai)
📚 [mcpd official docs](https://mozilla-ai.github.io/mcpd/)
---
Today, `mcpd` launches MCP servers as subprocesses using STDIO (Standard Input/Output) and acts as an HTTP proxy between agents and the tools they expose. This enables agent-compatible workflows with support for secrets, runtime arguments, and reproducible configurations, no matter where `mcpd` is running.
We're developing a Kubernetes operator, guided by our internal roadmap, to extend `mcpd` for deploying and managing MCP servers as long-lived services in production. It will use the same `.mcpd.toml` configuration and proxy model, making it easier to scale and manage lifecycles without changing the developer experience.
## The Problem
ML teams build agents that work perfectly locally. Operations teams often get handed Python scripts with little context and told "make this production-ready across dev/UAT/prod."
The gap between local development and enterprise deployment kills AI initiatives.
`mcpd` solves this with declarative configuration, secure secrets management, and seamless environment promotion - all while keeping the developer experience simple.
## Why `mcpd`?
**Zero-Config Tool Setup**
No need to clone multiple repos or install language-specific dependencies. `mcpd add` and `mcpd daemon` handle everything.
**Language-Agnostic Tooling**
Use MCP servers in Docker containers or written in Python, JavaScript, or TypeScript via a unified HTTP API.
**Declarative Configuration**
Version-controlled `.mcpd.toml` files define your agent infrastructure. Reproducible, auditable, CI-friendly.
**Enterprise-Ready Secrets**
Separate project configuration from runtime variables, and export sanitized secrets templates. No need to commit secrets to Git ever again.
**Seamless Local-to-Prod**
Same configuration works in development, CI, and cloud environments without modification or risky hand-offs.
## Built for Dev & Production
| Development Workflow | Production Benefit |
|-----------------------------------------------------------------------------------|------------------------------------------------------------|
| `mcpd daemon` runs everything locally | Same daemon runs in containers |
| `.mcpd.toml` version-controlled configs | Declarative infrastructure as code |
| Local secrets in `~/.config/mcpd/` | Secure secrets injection via control plane |
| `mcpd config export` exports version-control safe snapshot of local configuration | Sanitized secrets config and templates for CI/CD pipelines |
## Features
- Focus on Developer Experience via `mcpd` CLI
- Declarative configuration (`.mcpd.toml`) to define required servers/tools
- Run and manage language-agnostic MCP servers
- Secure execution context for secrets and runtime args
- Smooth dev-to-prod transition via the `mcpd` daemon
- Rich CLI and SDK tooling, see supported languages below:
## 🚀 Quick Start
### Prerequisites
You need the following installed before running `mcpd`:
- [**Docker**](https://www.docker.com/products/docker-desktop/)
- [**npx**](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (Node.js package runner)
- [**uvx**](https://docs.astral.sh/uv/getting-started/installation/) (Universal virtual environment manager)
If you are developing `mcpd`, you will also need:
- [**Go**](https://go.dev/doc/install) (v1.25.1+ recommended)
### Installation
#### 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 [mcpd's 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"
}
```
#### via local Go binary build
```bash
# Clone and build
git clone git@github.com:mozilla-ai/mcpd.git
cd mcpd
make build
sudo make install # Install mcpd 'globally' to /usr/local/bin
```
### Using mcpd
```bash
# Initialize a new project
mcpd init
# Add an MCP server
mcpd add time
# Set the local timezone for the MCP server
mcpd config args set time -- --local-timezone=Europe/London
# Start the daemon in dev mode with debug logging
mcpd daemon --dev --log-level=DEBUG --log-path=$(pwd)/mcpd.log
# You can tail the log file
tail -f mcpd.log
```
API docs will be available at [http://localhost:8090/docs](http://localhost:8090/docs).
## Deploy Anywhere
`mcpd` is runtime-flexible and infrastructure-agnostic:
- ⚙️ Works in any container or host with `uv` and `npx`
- ☁️ Multi-cloud ready (AWS, GCP, Azure, on-prem)
- ♻️ Low resource overhead via efficient server management
## SDKs
### `mcpd` SDKs
| Language | Repository | Status |
|------------|--------------------------------------------------------------------------|--------|
| Python | [mcpd-sdk-python](https://github.com/mozilla-ai/mcpd-sdk-python) | ✅ |
| JavaScript | [mcpd-sdk-javascript](https://github.com/mozilla-ai/mcpd-sdk-javascript) | ✅ |
### `mcpd` plugin SDKs
Plugin SDKs are built using the [mcpd plugin Protocol Buffers specification](https://github.com/mozilla-ai/mcpd-proto).
| Language | Repository | Status |
|----------|----------------------------------------------------------------------------------|--------|
| Go | [mcpd-plugins-sdk-go](https://github.com/mozilla-ai/mcpd-plugins-sdk-go) | ✅ |
| .NET | [mcpd-plugins-sdk-dotnet](https://github.com/mozilla-ai/mcpd-plugins-sdk-dotnet) | ✅ |
| Python | [mcpd-plugins-sdk-python](https://github.com/mozilla-ai/mcpd-plugins-sdk-python) | ✅ |
More on plugins soon!
## 💻 Development
Build local code:
```bash
make build
```
Run tests:
```bash
make test
```
Validate Mozilla AI registry (when modifying registry files):
```bash
make validate-registry
```
Run the local documentation site (requires `uv`), dynamically generates command line documentation:
```bash
make docs
```
---
## 🤝 Contributing
Please see our [Contributing to mcpd](CONTRIBUTING.md) guide for more information.
## 📄 License
[Licensed](LICENSE) under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
