# MCP Server PATH Configuration Solutions
## Problem
When using nvm (Node Version Manager), Claude Code cannot find `node` or `npx` because it doesn't inherit the shell's PATH environment variable.
## Solutions (Ranked by Preference)
### ✅ Solution 1: Set PATH in MCP Server env (Recommended)
**Method**: Add PATH directly to the MCP server's environment configuration.
**Configuration** (`~/.claude.json`):
```json
{
"mcpServers": {
"imaginepro": {
"type": "stdio",
"command": "npx",
"args": ["--package=imaginepro-mcp-server", "-y", "imaginepro-mcp"],
"env": {
"IMAGINEPRO_API_KEY": "your-key",
"PATH": "/Users/zenglei/.nvm/versions/node/v22.19.0/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
**Pros**:
- ✅ No full paths in command field
- ✅ Works reliably
- ✅ Standard JSON configuration
**Cons**:
- ⚠️ Hardcoded node version in PATH
- ⚠️ Need to update if node version changes
**Testing**:
```bash
# Verify it works
jq '.mcpServers.imaginepro' ~/.claude.json
```
---
### ✅ Solution 2: Shell Wrapper Script (Most Flexible)
**Method**: Create a wrapper script that loads nvm environment.
**Script** (`~/.local/bin/imaginepro-mcp-wrapper.sh`):
```bash
#!/usr/bin/env zsh
# Load nvm environment
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# Run the MCP server
exec npx --package=imaginepro-mcp-server -y imaginepro-mcp "$@"
```
**Configuration**:
```json
{
"mcpServers": {
"imaginepro": {
"type": "stdio",
"command": "/Users/zenglei/.local/bin/imaginepro-mcp-wrapper.sh",
"args": [],
"env": {
"IMAGINEPRO_API_KEY": "your-key"
}
}
}
}
```
**Setup**:
```bash
chmod +x ~/.local/bin/imaginepro-mcp-wrapper.sh
```
**Pros**:
- ✅ Automatically uses nvm's active node version
- ✅ No hardcoded paths
- ✅ Easy to update/maintain
- ✅ Can add additional logic if needed
**Cons**:
- ⚠️ Requires maintaining separate wrapper file
---
### ✅ Solution 3: Use Full Paths (Simplest but Less Elegant)
**Method**: Use absolute paths to npx.
**Configuration**:
```json
{
"mcpServers": {
"imaginepro": {
"type": "stdio",
"command": "/Users/zenglei/.nvm/versions/node/v22.19.0/bin/npx",
"args": ["--package=imaginepro-mcp-server", "-y", "imaginepro-mcp"],
"env": {
"IMAGINEPRO_API_KEY": "your-key"
}
}
}
}
```
**Pros**:
- ✅ Simple and explicit
- ✅ No extra files needed
**Cons**:
- ⚠️ Hardcoded node version
- ⚠️ Less portable across machines
---
### 🔧 Solution 4: Install Node System-Wide (Alternative Approach)
**Method**: Use Homebrew to install Node instead of nvm.
**Installation**:
```bash
brew install node
```
**Configuration**:
```json
{
"mcpServers": {
"imaginepro": {
"type": "stdio",
"command": "npx",
"args": ["--package=imaginepro-mcp-server", "-y", "imaginepro-mcp"],
"env": {
"IMAGINEPRO_API_KEY": "your-key"
}
}
}
}
```
**Pros**:
- ✅ Cleanest configuration
- ✅ npx available in standard PATH
- ✅ No special handling needed
**Cons**:
- ⚠️ Lose nvm version management
- ⚠️ May conflict with existing nvm setup
---
## Environment Variable Expansion
### Does Claude Code support ${PATH} or $HOME expansion?
**Partial Support**: Claude Code supports some environment variable expansion in certain contexts (like hooks), but behavior in MCP server config is not fully documented.
**Tested Approaches**:
1. **`${PATH}` expansion** - Not tested/confirmed in MCP env
```json
"env": {
"PATH": "${PATH}:/Users/zenglei/.nvm/versions/node/v22.19.0/bin"
}
```
2. **`$HOME` expansion** - Works in hooks, not confirmed for MCP
```json
"command": "$HOME/.local/bin/imaginepro-mcp-wrapper.sh"
```
3. **Direct environment reference** - Not supported
```json
"env": {
"PATH": "$PATH:/additional/path" // This won't expand
}
```
---
## Recommended Setup for Different Scenarios
### For Development (Current Project)
**Use Solution 1 or 2** - Set PATH in env or use wrapper script
### For Published Package Users
**Recommend** in README:
- Solution 4 (Homebrew) for simplicity
- Solution 1 (PATH in env) for nvm users
- Solution 2 (wrapper) for advanced users
### For CI/CD
**Use Solution 1** with explicit paths for reproducibility
---
## Current Configuration
**Global** (`~/.claude.json`):
```json
{
"mcpServers": {
"imaginepro": {
"type": "stdio",
"command": "npx",
"args": ["--package=imaginepro-mcp-server", "-y", "imaginepro-mcp"],
"env": {
"IMAGINEPRO_API_KEY": "eyJhbGc...",
"PATH": "${PATH}:/Users/zenglei/.nvm/versions/node/v22.19.0/bin"
}
}
}
}
```
**Project-specific** (`~/.claude.json` → projects → ...):
Same as global
---
## Testing Commands
```bash
# Check current config
jq '.mcpServers.imaginepro' ~/.claude.json
# Test npx directly
/Users/zenglei/.nvm/versions/node/v22.19.0/bin/npx --package=imaginepro-mcp-server -y imaginepro-mcp
# Test wrapper script
~/.local/bin/imaginepro-mcp-wrapper.sh
# Check PATH in current shell
echo $PATH | tr ':' '\n' | grep nvm
# Reconnect MCP servers
claude mcp list
```
---
## Troubleshooting
### Error: `spawn npx ENOENT`
**Cause**: npx not found in PATH
**Fix**: Use Solution 1, 2, or 3
### Error: `spawn node ENOENT`
**Cause**: node not found (affects local build)
**Fix**: Same as above
### Error: `imaginepro-mcp: command not found`
**Cause**: Trying to run binary directly instead of via npx
**Fix**: Use `npx --package=imaginepro-mcp-server -y imaginepro-mcp`
---
## Summary
**Best Practice**: Use **Solution 2 (wrapper script)** for maximum flexibility and automatic nvm version handling.
**Quickest Fix**: Use **Solution 1 (PATH in env)** for immediate resolution with minimal changes.
