Installation

MCPProxy can be installed on macOS, Windows, and Linux. Choose the installation method that works best for your platform.

macOS

Installer DMG (Recommended)

Requires macOS 13 (Ventura) or later (LSMinimumSystemVersion in the app bundle). On anything older the package installs but the app will not launch.

Download mcpproxy-<version>-darwin-arm64-installer.dmg (Apple Silicon) or -darwin-amd64-installer.dmg (Intel) from the releases page.

There is nothing to drag. The disk image contains a .pkg installer and a README.txt:

Open the DMG and double-click the .pkg file.
macOS asks for an administrator password — the package installs for all users, so this is required.
Follow the installer. There are no components to choose.
The installer launches mcpproxy for you when it finishes — look for the icon in your menu bar. If it is not there, open it from Applications.

Both the disk image and the package are signed and notarized by Apple.

What the installer puts on your machine

Path	What it is
`/Applications/mcpproxy.app`	The menu-bar app, with the headless core bundled inside it
`/usr/local/bin/mcpproxy`	Symlink to the core binary, so `mcpproxy` works in a terminal
`~/.mcpproxy/`	Your config, database and search index
`~/Library/Logs/mcpproxy/`	Logs (the macOS standard location, not `~/.mcpproxy/`)
`~/.mcpproxy/certs/ca.pem`	A local CA certificate, copied to disk only — see below

The ca.pem row is conditional: postinstall.sh copies it only when it can resolve a non-root $USER and the build actually bundled a certificate, and it has no console-user fallback, so the file may simply be absent. Nothing depends on it — mcpproxy trust-cert generates a certificate itself when none exists.

The installer does not change your system's certificate trust. The bundled ca.pem exists so that the optional HTTPS mode has a certificate available; trust is modified only if you later run mcpproxy trust-cert yourself, which defaults to the System keychain (--keychain=system) and asks for your password. The default mode is plain HTTP on 127.0.0.1:8080 and needs no certificate at all.

The installer also removes a stale LaunchAgent left behind by pre-0.5x builds. It does not configure auto-start — that is a per-user toggle in the tray menu ("Launch at Login").

Uninstalling

Quit the app first — from the tray menu, or pkill -x mcpproxy. Deleting the bundle does not stop a running process, and the tray is what shuts the core down cleanly.

sudo rm -rf /Applications/mcpproxy.app /usr/local/bin/mcpproxy
rm -rf ~/.mcpproxy ~/Library/Logs/mcpproxy   # config, database, index and logs

If you ran mcpproxy trust-cert, remove the certificate as well. It is in the System keychain unless you passed --keychain=login: open Keychain Access → System → Certificates and delete the MCPProxy CA.

Homebrew

Install the full macOS tray app (signed & notarized, bundles the core server):

brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy

Or install just the headless core CLI (no tray app):

brew install smart-mcp-proxy/mcpproxy/mcpproxy

Windows

Installer (Recommended)

Download the latest Windows installer (.exe) from the releases page.

The installer will:

Install MCPProxy to %LOCALAPPDATA%\Programs\mcpproxy
Add MCPProxy to your system PATH
Create Start Menu shortcuts

Manual Installation

Download the Windows binary from the releases page
Extract to a directory of your choice
Add the directory to your PATH

Linux

Debian / Ubuntu — apt repository (recommended)

Add the MCPProxy apt repository once; apt upgrade handles updates from then on, like any other system package.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update
sudo apt install mcpproxy

Supported architectures: amd64, arm64. See Linux Package Repositories for details on retention, pinning older versions, mirroring, and troubleshooting.

Repository signing key fingerprint: 3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B. You can verify it with gpg --show-keys against the public key URL above.

Fedora / RHEL / Rocky / AlmaLinux — dnf repository (recommended)

sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
sudo dnf install -y mcpproxy

Supported architectures: x86_64, aarch64.

Arch Linux — AUR (community-maintained)

MCPProxy is available on the Arch User Repository as mcpproxy-bin, which installs the official upstream binary plus a hardened systemd unit.

# With an AUR helper (recommended)
yay -S mcpproxy-bin

# Or manually with makepkg
git clone https://aur.archlinux.org/mcpproxy-bin.git
cd mcpproxy-bin
makepkg -si

The package installs mcpproxy to /usr/bin and ships a systemd user unit at /usr/lib/systemd/user/mcpproxy.service.

Enable it with:

Update cadence

Unlike the apt/dnf repositories above, AUR is community-driven: new versions land via the mcpproxy-bin PKGBUILD being bumped, not via a project-controlled mirror. The package is currently kept current by automation in the maintainer's updater repo, so bumps usually appear within a day of a GitHub release. If yay reports an old version after a recent release, you can flag the package "out-of-date" on AUR or fall back to the Tarball install below.

Debian / Ubuntu — direct `.deb` download (fallback)

If the apt repository isn't reachable (air-gapped installs, behind corporate proxies blocking mcpproxy.app, etc.), download the .deb from the releases page and install it locally.

One-liner (auto-detects latest version):

VERSION=$(curl -fsSL https://api.github.com/repos/smart-mcp-proxy/mcpproxy-go/releases/latest \
  | grep -oE '"tag_name": *"v[^"]+"' | sed -E 's/.*"v([^"]+)"/\1/')
ARCH=$(dpkg --print-architecture)   # amd64 or arm64
curl -fLO "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy_${VERSION}_${ARCH}.deb"
sudo apt install "./mcpproxy_${VERSION}_${ARCH}.deb"

Or pin a specific version:

# AMD64 (x86_64)
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/download/v0.24.2/mcpproxy_0.24.2_amd64.deb
sudo apt install ./mcpproxy_0.24.2_amd64.deb

# ARM64 (Raspberry Pi, AWS Graviton, etc.)
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/download/v0.24.2/mcpproxy_0.24.2_arm64.deb
sudo apt install ./mcpproxy_0.24.2_arm64.deb

The package installs mcpproxy to /usr/bin, ships a hardened systemd unit at /lib/systemd/system/mcpproxy.service, and creates a dedicated mcpproxy system user. The service is enabled and started automatically on first install. Subsequent upgrades preserve your config and try-restart the unit.

After install:

sudo systemctl status mcpproxy
sudo journalctl -u mcpproxy -f      # tail logs
sudo nano /etc/mcpproxy/mcp_config.json   # edit config (then restart)
sudo systemctl restart mcpproxy

Migrating from a manually-installed mcpproxy

If you've been running an older mcpproxy from a binary you dropped into /usr/local/bin/ with a hand-rolled systemd unit (typically running as your own user, with config under ~/.mcpproxy/), the apt/dnf install is a different layout. The deb/rpm runs as a dedicated mcpproxy system user with config in /etc/mcpproxy/ and state in /var/lib/mcpproxy/. Migration takes a couple of minutes; the only tricky bit is preserving paths your existing config references.

# 0. Stop and back up everything
sudo systemctl stop mcpproxy
sudo cp -a ~/.mcpproxy ~/mcpproxy-backup-$(date +%Y%m%d)
sudo cp ~/.mcpproxy/mcp_config.json ~/mcpproxy-config-backup-$(date +%Y%m%d).json

# 1. Remove the old service + binaries
sudo systemctl disable mcpproxy
sudo rm /etc/systemd/system/mcpproxy.service \
        /etc/systemd/system/multi-user.target.wants/mcpproxy.service
sudo systemctl daemon-reload
sudo mv /usr/local/bin/mcpproxy /usr/local/bin/mcpproxy.pre-deb.bak  # keep one rollback

# 2. Install the deb (follow the "apt repository (recommended)" section above)
#    The service starts immediately on a fresh config — stop it before migrating state.
sudo systemctl stop mcpproxy

# 3. Carry state across. config.db preserves quarantine + tool-approval state;
#    skip this copy if you'd rather start clean and re-approve every tool.
sudo cp ~/.mcpproxy/config.db          /var/lib/mcpproxy/config.db
sudo cp ~/.mcpproxy/mcp_config.json    /etc/mcpproxy/mcp_config.json
sudo chown -R mcpproxy:mcpproxy /var/lib/mcpproxy
sudo chown root:mcpproxy /etc/mcpproxy/mcp_config.json
sudo chmod 0640 /etc/mcpproxy/mcp_config.json

# 4. Rewrite any home-relative paths inside the migrated config.
#    The new service can't read /home/<you>/ because the unit sets ProtectHome=true.
sudo sed -i.bak \
    -e "s|\"data_dir\": \"$HOME/.mcpproxy\"|\"data_dir\": \"/var/lib/mcpproxy\"|g" \
    /etc/mcpproxy/mcp_config.json
sudo grep -nE "$HOME" /etc/mcpproxy/mcp_config.json   # should print nothing

# 5. If any stdio server uses `docker run`, give the mcpproxy user docker access:
sudo usermod -aG docker mcpproxy

# 6. Start it
sudo systemctl start mcpproxy
sudo systemctl status mcpproxy --no-pager

Things to watch for after step 6:

Secrets files referenced from the config: if any of your stdio servers source an env file from your home directory (e.g. set -a; source ~/.mcpproxy/foo.env; ...), copy that file to /etc/mcpproxy/ with root:mcpproxy 0640 ownership and update the path inside mcp_config.json. ProtectHome=true will otherwise make the file invisible to the service.
Custom data_dir or cache paths: the same sed pattern as step 4 — anything under $HOME becomes invisible.
Snap-installed Docker: on Ubuntu hosts where Docker came from snap (the default on 24.04), mcpproxy doctor will warn about additional one-time host setup (loginctl enable-linger mcpproxy, snap set system homedirs=/var/lib, and a systemd drop-in). Follow the snippet doctor prints, then sudo systemctl restart mcpproxy. The error you'd see otherwise is cannot create XDG_RUNTIME_DIR folder "/run/user/<uid>/snap.docker".

Once you've confirmed the new service is healthy (mcpproxy doctor reports no issues), you can delete the backups under ~/mcpproxy-backup-* — but the deb keeps your config intact across future upgrades regardless.

Network exposure: localhost by default

Both .deb and .rpm packages ship a default config that binds only to 127.0.0.1:8080 — meaning the service is reachable only from the same machine. This is intentional: MCPProxy proxies tools that can read your filesystem, call paid APIs, and execute code, so a wide-open default would be unsafe.

You can confirm the default in the shipped example:

cat /etc/mcpproxy/mcp_config.json
# {
#   "listen": "127.0.0.1:8080",
#   ...
# }

Reaching it from another host on your LAN

If you're installing on a server (a homelab box, a VPS, a Raspberry Pi) and you want other machines to connect to it, you need to do two things:

Switch the listen address from 127.0.0.1:8080 to 0.0.0.0:8080 (all interfaces) or to a specific LAN IP.
Set an api_key so the REST API and tray-style endpoints aren't anonymously accessible. MCPProxy auto-generates one on first start if you leave the field empty, but for a network-exposed install you should set it explicitly to a strong random value.

Example:

# Generate a strong random API key
API_KEY=$(openssl rand -hex 32)

# Edit the config
sudo tee /etc/mcpproxy/mcp_config.json >/dev/null <<EOF
{
  "listen": "0.0.0.0:8080",
  "api_key": "${API_KEY}",
  "data_dir": "/var/lib/mcpproxy",
  "enable_socket": true,
  "enable_web_ui": true,
  "require_mcp_auth": false,
  "mcpServers": []
}
EOF

# Restart so the new bind takes effect
sudo systemctl restart mcpproxy

# From another machine on the LAN:
curl -H "X-API-Key: ${API_KEY}" http://<server-ip>:8080/api/v1/status

Security checklist before exposing on a LAN

Always set a non-empty api_key. The REST API enforces it, but a network-reachable instance with an obvious or empty key is one curl away from full tool execution.
Put a firewall in front. If only one workstation needs access, prefer binding to a single LAN IP (e.g. "listen": "192.168.1.10:8080") or restrict port 8080 in ufw/firewalld to known source addresses.
Consider require_mcp_auth: true if you also want the /mcp endpoint to require the API key. It's false by default for AI-client compatibility.
Don't expose to the public internet without TLS in front. Run nginx/Caddy/Traefik as a reverse proxy with HTTPS, or tunnel via Tailscale/WireGuard/SSH. The built-in HTTP server is not designed to be a public ingress.

For a deeper dive on auth, agent tokens, and the security model, see the Configuration Reference and the REST API reference.

Fedora / RHEL / CentOS / openSUSE — direct `.rpm` download (fallback)

For air-gapped or offline installs where the dnf repository isn't reachable.

One-liner (auto-detects latest version):

VERSION=$(curl -fsSL https://api.github.com/repos/smart-mcp-proxy/mcpproxy-go/releases/latest \
  | grep -oE '"tag_name": *"v[^"]+"' | sed -E 's/.*"v([^"]+)"/\1/')
ARCH=$(uname -m)   # x86_64 or aarch64
curl -fLO "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-${VERSION}-1.${ARCH}.rpm"
sudo dnf install "./mcpproxy-${VERSION}-1.${ARCH}.rpm"

Or pin a specific version:

# AMD64 (x86_64)
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/download/v0.24.2/mcpproxy-0.24.2-1.x86_64.rpm
sudo dnf install ./mcpproxy-0.24.2-1.x86_64.rpm

# ARM64 (aarch64)
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/download/v0.24.2/mcpproxy-0.24.2-1.aarch64.rpm
sudo dnf install ./mcpproxy-0.24.2-1.aarch64.rpm

The same systemctl workflow applies. On systems without dnf, use sudo rpm -i ./mcpproxy-*.rpm or sudo zypper install ./mcpproxy-*.rpm.

Tarball (any distro)

If you don't want a system service or you're on a distro without .deb/.rpm support, grab the raw binary tarball:

# AMD64
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz
tar -xzf mcpproxy-latest-linux-amd64.tar.gz
sudo install -m 0755 mcpproxy /usr/local/bin/

# ARM64
curl -LO https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz
tar -xzf mcpproxy-latest-linux-arm64.tar.gz
sudo install -m 0755 mcpproxy /usr/local/bin/

You can then run mcpproxy serve directly, or wire up your own systemd unit modelled on the one shipped in the .deb/.rpm.

Package layout (.deb / .rpm)

Path	Purpose
`/usr/bin/mcpproxy`	Binary
`/lib/systemd/system/mcpproxy.service`	Hardened systemd unit (runs as `mcpproxy` user)
`/etc/mcpproxy/mcp_config.json`	Config (`config
`/etc/mcpproxy/mcp_config.json.example`	Reference example, refreshed on upgrade
`/var/lib/mcpproxy/`	Data dir (BBolt DB, search index, per-server logs)
`/usr/share/doc/mcpproxy/{LICENSE,README.md}`	Documentation

The systemd unit launches mcpproxy with --config=/etc/mcpproxy/mcp_config.json --data-dir=/var/lib/mcpproxy and uses NoNewPrivileges, ProtectSystem=strict, PrivateTmp, and friends.

Verify Installation

After installation, verify MCPProxy is working:

mcpproxy --version

Next Steps

Once installed, proceed to the Quick Start guide to configure and run MCPProxy.

macOS​

Installer DMG (Recommended)​

What the installer puts on your machine​

Uninstalling​

Homebrew​

Windows​

Installer (Recommended)​

Manual Installation​

Linux​

Debian / Ubuntu — apt repository (recommended)​

Fedora / RHEL / Rocky / AlmaLinux — dnf repository (recommended)​

Arch Linux — AUR (community-maintained)​

Debian / Ubuntu — direct .deb download (fallback)​

Migrating from a manually-installed mcpproxy​

Network exposure: localhost by default​

Reaching it from another host on your LAN​

Fedora / RHEL / CentOS / openSUSE — direct .rpm download (fallback)​

Tarball (any distro)​

Package layout (.deb / .rpm)​

Verify Installation​

Next Steps​