Homebrew Tap for mcpproxy
This repository contains the Homebrew formula for mcpproxy, a Smart MCP Proxy for intelligent tool discovery and proxying for Model Context Protocol servers.
Installation
Quick Install
brew install smart-mcp-proxy/mcpproxy/mcpproxy
Manual Tap and Install
# Add the tap
brew tap smart-mcp-proxy/mcpproxy
# Install mcpproxy
brew install mcpproxy
Usage
After installation, you can use mcpproxy directly:
# Show version
mcpproxy --version
# Show help
mcpproxy --help
# Run with default settings
mcpproxy
# Run with custom config
mcpproxy --config /path/to/config.yaml
# Run with custom data directory
mcpproxy --data-dir /path/to/data
# Enable tray mode (default)
mcpproxy --tray
# Disable tray mode
mcpproxy --tray=false
⚠️ IMPORTANT: Auto-Update Compatibility
If you installed mcpproxy via Homebrew, you MUST disable the built-in auto-update feature to avoid conflicts with Homebrew's package management.
mcpproxy includes a built-in auto-updater that can replace the binary, which conflicts with Homebrew's expectations. When installed via Homebrew:
- The built-in updater will be automatically disabled (planned feature)
- Use Homebrew for updates instead:
brew update
brew upgrade mcpproxy
- If auto-update happens accidentally, reinstall via Homebrew:
brew reinstall mcpproxy
Current Auto-Update Behavior
mcpproxy currently includes these auto-update features:
- Daily checks for new releases from GitHub
- "Check for Updates..." option in system tray menu
- Automatic binary replacement when updates are found
These features work well for direct installations but can cause issues with package manager installations.
Auto-Start on macOS
Option 1: Using launchctl (Recommended)
Create a LaunchAgent to start mcpproxy automatically on login:
# Option A: Download the plist file from this repository
curl -o ~/Library/LaunchAgents/com.smartmcpproxy.mcpproxy.plist \
https://raw.githubusercontent.com/smart-mcp-proxy/homebrew-mcpproxy/main/com.smartmcpproxy.mcpproxy.plist
# Option B: Create the plist file manually
cat > ~/Library/LaunchAgents/com.smartmcpproxy.mcpproxy.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.smartmcpproxy.mcpproxy</string>
<key>Program</key>
<string>/opt/homebrew/bin/mcpproxy</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/mcpproxy</string>
<string>--tray=true</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ProcessType</key>
<string>Interactive</string>
<key>StandardOutPath</key>
<string>/tmp/mcpproxy.out</string>
<key>StandardErrorPath</key>
<string>/tmp/mcpproxy.err</string>
</dict>
</plist>
EOF
# Load the LaunchAgent
launchctl load ~/Library/LaunchAgents/com.smartmcpproxy.mcpproxy.plist
# Start immediately
launchctl start com.smartmcpproxy.mcpproxy
Note: If you have mcpproxy installed in a different location (e.g., Intel Mac uses /usr/local/bin/mcpproxy), update the path in the plist file accordingly.
Option 2: macOS Login Items
- Open System Settings → General → Login Items
- Click the + button under "Open at Login"
- Navigate to
/opt/homebrew/bin/mcpproxy and add it
- Optionally check "Hide" to start minimized to tray
Removing Auto-Start
Remove LaunchAgent:
# Stop the service
launchctl stop com.smartmcpproxy.mcpproxy
# Unload the LaunchAgent
launchctl unload ~/Library/LaunchAgents/com.smartmcpproxy.mcpproxy.plist
# Remove the plist file
rm ~/Library/LaunchAgents/com.smartmcpproxy.mcpproxy.plist
Remove from Login Items:
- Open System Settings → General → Login Items
- Find mcpproxy in the list and click the - button
Troubleshooting Auto-Start
Check LaunchAgent Status:
# List all LaunchAgents (look for mcpproxy)
launchctl list | grep mcpproxy
# Check logs
tail -f /tmp/mcpproxy.out /tmp/mcpproxy.err
Common Issues:
- Path not found: Update the path in the plist if mcpproxy is installed elsewhere
- Permission denied: Ensure the binary is executable:
chmod +x /opt/homebrew/bin/mcpproxy
- Tray not showing: The app needs to run in an interactive session with GUI access
Updating
To update mcpproxy to the latest version:
brew update
brew upgrade mcpproxy
Uninstalling
To remove mcpproxy:
brew uninstall mcpproxy
To remove the tap:
brew untap smart-mcp-proxy/mcpproxy
Development
This formula is maintained as part of the mcpproxy project. For issues related to the Homebrew formula, please open an issue in the main mcpproxy repository.
Updating the Formula
When new versions of mcpproxy are released, this formula needs to be updated:
Get the new SHA256:
curl -sL "https://github.com/smart-mcp-proxy/mcpproxy-go/archive/refs/tags/vX.X.X.tar.gz" | shasum -a 256
Update Formula/mcpproxy.rb:
- Change the
url to point to the new version tag
- Replace the
sha256 with the new hash
Test the update:
brew install --build-from-source ./Formula/mcpproxy.rb
brew test mcpproxy
Commit and push:
git add Formula/mcpproxy.rb
git commit -m "Update mcpproxy to vX.X.X"
git push origin main
Updating the Cask
The cask (Casks/mcpproxy.rb) installs the pre-built MCPProxy tray app (GUI)
from the release DMGs. Unlike the formula it is not built from source and
has no test do block, so brew test and brew install --build-from-source
do not apply to it.
When a new version of mcpproxy is released, update the cask as follows:
Get the new SHA256 for both DMGs (arm64 and amd64):
VERSION=X.X.X
for arch in arm64 amd64; do
curl -sL "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/download/v${VERSION}/mcpproxy-${VERSION}-darwin-${arch}-installer.dmg" \
| shasum -a 256
done
Update Casks/mcpproxy.rb:
- Bump
version to the new release
- Replace the
sha256 in the on_arm block (arm64 DMG) and the sha256 in
the on_intel block (amd64 DMG)
Validate the cask (casks have no test do block, so there is no
brew test step):
# Lint (rubocop). Auto-fix correctable offenses with --fix:
brew style Casks/mcpproxy.rb
brew style --fix Casks/mcpproxy.rb
# Audit. `brew audit <path>` is disabled, so audit by tap name:
brew audit --cask --online smart-mcp-proxy/mcpproxy/mcpproxy
Commit and push:
git add Casks/mcpproxy.rb
git commit -m "Update mcpproxy cask to vX.X.X"
git push origin main
Recommendations for mcpproxy Development
To improve Homebrew compatibility, consider these enhancements to mcpproxy:
Add environment variable detection:
// Disable auto-update when installed via package manager
if os.Getenv("HOMEBREW_PREFIX") != "" {
// Disable built-in updater
autoUpdateEnabled = false
}
Add --disable-auto-update flag:
mcpproxy --disable-auto-update --tray=true
Detection via binary path:
// Check if running from Homebrew installation
execPath, _ := os.Executable()
if strings.Contains(execPath, "/homebrew/") || strings.Contains(execPath, "/usr/local/") {
// Likely installed via Homebrew
autoUpdateEnabled = false
}
License
This Homebrew formula is licensed under the same license as mcpproxy.