Client Can't Find forge

Symptoms

• Running forge in a terminal returns command not found: forge or forge: command not found.
• Your MCP client reports “spawn failed” or a similar error when trying to start the Forge server.
• which forge returns no output.

---

Likely Causes

Cause	Indicator
Forge has not been installed	which forge returns nothing
Binary is installed but not in PATH	Binary exists at a known path but forge fails
Shell profile not sourced	Works in a new terminal but not an existing one
Wrong shell (zsh vs bash)	PATH set in .bashrc but running zsh
macOS Gatekeeper quarantine	”cannot be opened” error — see Binary Won’t Run on macOS

---

Step-by-Step Fix

Step 1: Confirm forge is not installed

which forge
ls ~/.local/bin/forge 2>/dev/null || echo "not at ~/.local/bin"
ls /usr/local/bin/forge 2>/dev/null || echo "not at /usr/local/bin"

If none of these paths have the binary, proceed to Step 2. If the binary exists but forge still fails, skip to Step 3.

Step 2: Install forge

Download the binary for your platform from https://forge.ironpinelabs.com/docs/getting-started/install-forge/. Installation is a single file copy:

macOS (Apple Silicon):

curl -fsSL https://downloads.forge.ironpinelabs.com/latest/forge-macos-aarch64 -o forge
chmod +x forge
sudo mv forge /usr/local/bin/forge

macOS (Intel):

curl -fsSL https://downloads.forge.ironpinelabs.com/latest/forge-macos-x86_64 -o forge
chmod +x forge
sudo mv forge /usr/local/bin/forge

Linux (x86-64):

curl -fsSL https://downloads.forge.ironpinelabs.com/latest/forge-linux-x86_64 -o forge
chmod +x forge
sudo mv forge /usr/local/bin/forge

Linux (ARM64):

curl -fsSL https://downloads.forge.ironpinelabs.com/latest/forge-linux-aarch64 -o forge
chmod +x forge
sudo mv forge /usr/local/bin/forge

Verify the SHA-256 checksum from https://downloads.forge.ironpinelabs.com/latest/latest.json before running.

Step 3: Add the binary location to PATH

If the binary is installed but not in your PATH, add the directory containing it to your shell profile.

For ~/.local/bin/forge (common for user-local installs):

bash (edit ~/.bashrc or ~/.bash_profile):

export PATH="$HOME/.local/bin:$PATH"

zsh (edit ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

fish (edit ~/.config/fish/config.fish):

set -gx PATH $HOME/.local/bin $PATH

After editing, reload your shell profile:

source ~/.bashrc    # bash
source ~/.zshrc     # zsh

Or open a new terminal window.

Step 4: Verify

which forge
forge --version

Expected output:

/usr/local/bin/forge
forge 1.3.0

Step 5: Use absolute paths in .mcp.json

If your MCP client still cannot find forge after PATH is set, use the absolute path in .mcp.json rather than relying on PATH resolution:

{
  "mcpServers": {
    "forge": {
      "command": "/usr/local/bin/forge",
      "args": ["serve", "/path/to/your/repo"]
    }
  }
}

Replace /usr/local/bin/forge with the output of which forge. GUI applications (like VS Code) may launch with a different PATH than your terminal.

---

When to Escalate

Contact support at [email protected] if:

• You have placed the binary in a standard location (/usr/local/bin) and it still returns command not found.
• You are on a managed machine where sudo mv is not available and your organization controls PATH.

Include the output of:

echo $PATH
uname -a
ls -la /usr/local/bin/forge 2>/dev/null || echo "not found"