Installation

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

macOS

DMG Installer (Recommended)

Download the latest .dmg file from the releases page and drag MCPProxy to your Applications folder.

The DMG installers are signed and notarized by Apple.

Homebrew

brew tap smart-mcp-proxy/mcpproxy
brew install 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​

DMG Installer (Recommended)​

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​