setup

Replicate MCP Setup

Automatically detect, install, and configure everything needed for image generation. Run each step in order — skip steps that are already satisfied.

Step 1: Check if Already Working

Check whether you have access to any tools starting with mcp__replicate__.

If Replicate MCP tools are available:

1. Run mcp__replicate__get_account to verify the token works.
2. If it succeeds: report "Replicate MCP is ready. Generate images by asking Claude to create any visual asset." and STOP.
3. If it fails with an auth error: the token is bad — jump to Step 4 (Token Setup).

If no Replicate MCP tools are found: continue to Step 2.

Step 2: Check Node.js and npm

Run these checks via Bash:

echo "=== node ===" && which node && node --version || echo "MISSING"
echo "=== npm ===" && which npm && npm --version || echo "MISSING"
echo "=== npx ===" && which npx && npx --version || echo "MISSING"

If all three are present and node >= v18: skip to Step 3.

If Node.js is missing or too old (< v18): detect the platform and offer to install.

Detect Platform

echo "=== platform ===" && uname -s && uname -m
echo "=== package manager ===" && which brew 2>/dev/null && echo "homebrew" || which apt 2>/dev/null && echo "apt" || which dnf 2>/dev/null && echo "dnf" || which pacman 2>/dev/null && echo "pacman" || echo "unknown"

Install Node.js

Tell the user what you're about to do and ask for confirmation:

"Node.js is required for the Replicate MCP server. I'd like to install it via [detected method]. OK?"

Then use the appropriate method:

macOS (Homebrew):

brew install node

Ubuntu/Debian (apt) — use NodeSource for a current version:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

If sudo is unavailable or the user declines root access, suggest nvm instead:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install 22

Fedora/RHEL (dnf):

sudo dnf install -y nodejs

Arch (pacman):

sudo pacman -S nodejs npm

Windows (WSL): Use the Ubuntu/Debian instructions above inside WSL.

Unknown platform or no package manager: suggest installing from https://nodejs.org/en/download or using nvm (the curl command above works on any Linux/macOS).

After install, verify by re-running the checks from the top of this step. If node/npm/npx are still missing, STOP and report the error — don't proceed with a broken toolchain.

npm/npx edge cases

• npx installed but "command not found" in MCP context — this is the most common gotcha. Claude Code spawns MCP servers as child processes that may not inherit the user's full PATH (especially with nvm or non-standard installs). The fix is to use the absolute path to npx when registering:

  # Find where npx lives
  which npx
  # Use the full path in the MCP registration (Step 3)
  claude mcp add -s user replicate -- /usr/local/bin/npx -y replicate-mcp@latest
  

  If the user installed Node via nvm, the path will be something like ~/.nvm/versions/node/v22.x.x/bin/npx — use that instead.
• npx missing but npm present — older npm version. Fix: npm install -g npx
• npm permission errors (EACCES) — npm cache permissions. Fix:

  mkdir -p ~/.npm && npm config set cache ~/.npm
  

Step 3: Register Replicate MCP with Claude Code

Check if the MCP server is already registered:

claude mcp list 2>&1 | grep -i replicate

First, resolve the absolute path to npx (avoids PATH issues in MCP subprocess environments):

NPX_PATH=$(which npx)
echo "npx is at: $NPX_PATH"

If already registered but showing "Failed to connect": likely a token issue or stale registration. Remove and re-add:

claude mcp remove replicate
claude mcp add -s user replicate -- "$NPX_PATH" -y replicate-mcp@latest

If not registered:

claude mcp add -s user replicate -- "$NPX_PATH" -y replicate-mcp@latest

Using the absolute path (e.g., /usr/local/bin/npx) instead of bare npx prevents "command not found" errors in the MCP subprocess — the most commonly reported setup failure. The -s user flag registers it globally (not per-project) so image generation works in any project.

After registration, verify:

claude mcp list 2>&1 | grep -i replicate

Common failures at this step:

Symptom	Fix
"npx: command not found"	Step 2 didn't complete — go back and fix Node.js
"EACCES permission denied"	mkdir -p ~/.npm && npm config set cache ~/.npm then retry
Network/proxy errors downloading replicate-mcp	Check HTTP_PROXY/HTTPS_PROXY env vars, or npm config set registry https://registry.npmjs.org/
"Error: Cannot find module"	Stale npx cache: rm -rf ~/.npm/_npx then retry

Step 4: API Token Setup

Check if the token is already set:

echo "${REPLICATE_API_TOKEN:+SET}" || echo "NOT_SET"

If already set: skip to Step 5.

If not set: the user needs to create one on Replicate's website. Tell them:

"I need a Replicate API token to connect to the image generation service.

1. Go to replicate.com and sign up (or log in)
2. Go to Account Settings > API Tokens (replicate.com/account/api-tokens)
3. Click Create token, give it a name, and copy it
4. Paste it here — I'll configure it for you"

When the user provides the token:

1. Validate format — should start with r8_ and be 40+ characters. If it looks wrong, ask them to double-check.
2. Persist to shell profile (idempotent):

# Detect the user's actual shell profile
if [[ "$SHELL" == */zsh ]]; then
    PROFILE="$HOME/.zshrc"
else
    PROFILE="$HOME/.bashrc"
fi

if grep -q 'REPLICATE_API_TOKEN' "$PROFILE" 2>/dev/null; then
    sed -i.bak "s|^export REPLICATE_API_TOKEN=.*|export REPLICATE_API_TOKEN=\"TOKEN_HERE\"|" "$PROFILE"
    echo "Updated existing token in $PROFILE"
else
    echo "" >> "$PROFILE"
    echo "# Replicate API token for image generation" >> "$PROFILE"
    echo "export REPLICATE_API_TOKEN=\"TOKEN_HERE\"" >> "$PROFILE"
    echo "Added token to $PROFILE"
fi

(Replace TOKEN_HERE with the actual token value.)

3. Export for the current shell session too:

export REPLICATE_API_TOKEN="<token>"

Security reminder: The token lives in the shell profile (not in any repo). Never echo or log the full token value.

Step 5: Verify and Report

Report what was configured:

Setup complete!
  Node.js:       [version]
  npm:           [version]  
  Replicate MCP: registered (user scope)
  API token:     configured in [profile path]

Then tell the user:

"Restart Claude Code (or start a new session) for the MCP tools to appear. Then try: 'generate an icon of a gold star' to test."

If the user can't restart right now, explain that the MCP registration takes effect on the next session start — this is how Claude Code's MCP system works, not something we can change.

Troubleshooting

If the user comes back with issues after setup:

Symptom	Cause	Fix
"npx: command not found" in MCP but npx works in terminal	MCP subprocess doesn't inherit full PATH	Re-register with absolute path: claude mcp add -s user replicate -- $(which npx) -y replicate-mcp@latest
"replicate: ... ✗ Failed to connect"	Token not set or expired	Check echo $REPLICATE_API_TOKEN, regenerate at replicate.com if needed
MCP tools missing after restart	Registration didn't persist	Re-run with -s user flag and absolute npx path
"401 Unauthorized" from Replicate	Bad or expired token	Generate a new token at replicate.com/account/api-tokens
npx downloads packages every time	Normal for npx -y	First run is slow (~10s), subsequent runs use npm cache
generate-image skill says "Replicate MCP not detected"	MCP registered but session not restarted	Restart Claude Code — MCP servers load at session start
nvm-installed Node not found by MCP	nvm only loads in interactive shells	Use full path: ~/.nvm/versions/node/v22.x.x/bin/npx in the registration command