The Complete Guide to Fixing MCP Server PATH Problems

With a Focus on the “spawn uvx ENOENT” Error

πŸ“‹ Table of Contents

  1. The Problem and Its Symptoms
  2. Root Cause Analysis
  3. Immediate Fixes
  4. Platform-Specific Notes
  5. Prevention for Developers
  6. Testing and Verification
  7. Quick-Fix Checklist

The Problem and Its Symptoms

πŸ”₯ The Actual Error Log

1
2
2025-07-14T01:02:03.249Z [MCP-timeserver] [error] spawn uvx ENOENT
{"context":"connection","stack":"Error: spawn uvx ENOENT\n    at ChildProcess._handle.onexit (node:internal/child_process:285:19)"}

πŸ€” What Doesn’t Add Up

  • βœ… uvx --version works fine in the terminal
  • βœ… which uvx returns /Users/username/.local/bin/uvx
  • ❌ Only Claude Desktop throws a “uvx not found” error
  • βœ… With the same config, npx and sh work fine

Root Cause Analysis

🎯 The Core Issue: PATH Differs Between GUI and Shell Environments

Interactive Shell Environment (Terminal)

1
2
3
4
5
6
7
# 터미널 μ‹œμž‘ μ‹œ μ‹€ν–‰λ˜λŠ” μ„€μ • νŒŒμΌλ“€
~/.zshrc β†’ export PATH="/Users/username/.local/bin:$PATH"
~/.bash_profile β†’ export PATH="/Users/username/.local/bin:$PATH"

# κ²°κ³Ό PATH
echo $PATH
# /Users/username/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin

GUI Application Environment (Claude Desktop)

1
2
3
4
5
# GUI 앱이 λ³΄λŠ” κΈ°λ³Έ PATH (macOS launchdλ‘œλΆ€ν„° 상속)
/usr/bin:/bin:/usr/sbin:/sbin

# μ‚¬μš©μž μ»€μŠ€ν…€ κ²½λ‘œλŠ” ν¬ν•¨λ˜μ§€ μ•ŠμŒ!
# ~/.local/bin, /opt/homebrew/bin 등이 λˆ„λ½

πŸ“Š Where Each Command Lives

CommandTypical install locationReachable from GUI environment
sh/bin/shβœ…
npx/usr/local/bin/npxβœ…
uvx~/.local/bin/uvx❌
cargo~/.cargo/bin/cargo❌

Immediate Fixes

Edit claude_desktop_config.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "PATH": "/Users/username/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Pros:

  • βœ… Independent, per-project configuration
  • βœ… Dependencies are explicit when you move to another system
  • βœ… No effect on other apps

πŸ›‘οΈ Option 2: Use an Absolute Path

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "my-server": {
      "command": "/Users/username/.local/bin/uvx",
      "args": ["my-mcp-server"]
    }
  }
}

Pros:

  • βœ… Works immediately

  • βœ… No environment variables to set Cons:

  • ❌ Hardcoded path

  • ❌ The path may be different on another system

βš™οΈ Option 3: Set PATH at the System Level

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 1. ν˜„μž¬ μ„Έμ…˜μ— 적용
launchctl setenv PATH "/Users/username/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

# 2. 영ꡬ μ„€μ • (plist 파일 생성)
cat > ~/Library/LaunchAgents/setenv.PATH.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>setenv.PATH</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/launchctl</string>
        <string>setenv</string>
        <string>PATH</string>
        <string>/Users/username/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

# 3. plist λ‘œλ“œ
launchctl load ~/Library/LaunchAgents/setenv.PATH.plist

# 4. 확인
launchctl getenv PATH

Platform-Specific Notes

🍎 macOS

  • Problem: GUI apps don’t read shell config files
  • Fix: Set PATH with launchctl or in each app’s own settings
  • Test: Check the GUI environment’s PATH with launchctl getenv PATH

πŸͺŸ Windows

  • Problem: Environment variables differ between a PowerShell session and GUI apps
  • Fix: Edit Path in the system environment variables (permanent)
  • Caution: Apps need to be restarted after changing environment variables
1
2
3
4
5
:: Windowsμ—μ„œ μ‚¬μš©μž Path 확인
echo %PATH%

:: μ‹œμŠ€ν…œ ν™˜κ²½ λ³€μˆ˜ GUI둜 μ„€μ •
:: Win + R β†’ sysdm.cpl β†’ ν™˜κ²½ λ³€μˆ˜ β†’ μ‚¬μš©μž λ³€μˆ˜μ˜ Path νŽΈμ§‘

🐳 Docker

  • Fix: Set it explicitly with ENV in the Dockerfile
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
FROM python:3.10-slim

# μ»€μŠ€ν…€ 도ꡬ μ„€μΉ˜
COPY --from=builder /path/to/uvx /usr/local/bin/uvx
RUN chmod +x /usr/local/bin/uvx

# PATH λͺ…μ‹œμ  μ„€μ • (ꢌμž₯)
ENV PATH="/usr/local/bin:${PATH}"

CMD ["python", "mcp_server.py"]

Prevention for Developers

πŸ—οΈ 1. Bundle Your Dependencies (The Best Solution)

1
2
3
4
5
6
// Electron μ•± μ˜ˆμ‹œ: μ•± νŒ¨ν‚€μ§€μ— λ°”μ΄λ„ˆλ¦¬ 포함
const path = require('path');
const { spawn } = require('child_process');

const uvxPath = path.join(__dirname, '..', 'bin', process.platform, 'uvx');
const child = spawn(uvxPath, ['my-server']);

βš™οΈ 2. Let the Config Specify the Executable Path

1
2
3
4
5
6
7
8
9
{
  "mcpServers": {
    "my-server": {
      "executablePath": "/Users/username/.local/bin/uvx",
      "args": ["my-server"],
      "env": {...}
    }
  }
}

πŸ“ 3. Clear Error Messages (Can Be Applied Right Away)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// κΈ°μ‘΄: λͺ¨ν˜Έν•œ μ—λŸ¬
// Error: spawn uvx ENOENT

// κ°œμ„ : ꡬ체적인 μ•ˆλ‚΄
const errorMessage = `
❌ 'uvx' μ‹€ν–‰ νŒŒμΌμ„ 찾을 수 μ—†μŠ΅λ‹ˆλ‹€.

ν•΄κ²° 방법:
1. MCP μ„€μ •μ—μ„œ env.PATH에 uvx 경둜 μΆ”κ°€:
   "env": { "PATH": "/Users/username/.local/bin:$PATH" }

2. λ˜λŠ” μ ˆλŒ€ 경둜 μ‚¬μš©:
   "command": "/Users/username/.local/bin/uvx"

3. uvx μ„€μΉ˜ 확인:
   ν„°λ―Έλ„μ—μ„œ 'which uvx' μ‹€ν–‰ ν›„ 경둜 확인

μžμ„Έν•œ μ„€μ • 방법: https://docs.example.com/path-setup
`;

πŸ” 4. An Environment Diagnostic Tool

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// κ°œλ°œμžκ°€ 문제λ₯Ό μ‰½κ²Œ 진단할 수 μžˆλŠ” 헬퍼
function diagnosePath() {
  console.log('=== PATH 진단 ===');
  console.log('Current PATH:', process.env.PATH);
  console.log('PATH entries:', process.env.PATH.split(':'));

  const commonPaths = [
    '/usr/local/bin',
    '/opt/homebrew/bin',
    process.env.HOME + '/.local/bin',
    process.env.HOME + '/.cargo/bin'
  ];

  commonPaths.forEach(path => {
    const exists = require('fs').existsSync(path);
    const inPath = process.env.PATH.includes(path);
    console.log(`${path}: exists=${exists}, inPath=${inPath}`);
  });
}

Testing and Verification

πŸ§ͺ Testing Environment Differences in CI/CD

GitHub Actions example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: MCP PATH Test
on: [push]

jobs:
  test-path-handling:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3

      # uvx μ„€μΉ˜
      - name: Install uvx
        run: pip install uvx

      # κΈ°λ³Έ PATHμ—μ„œ ν…ŒμŠ€νŠΈ (μ‹€νŒ¨ μ˜ˆμƒ)
      - name: Test with minimal PATH
        run: |
          env -i PATH=/usr/bin:/bin node test-mcp.js          
        continue-on-error: true

      # μˆ˜μ •λœ μ„€μ •μœΌλ‘œ ν…ŒμŠ€νŠΈ (성곡 μ˜ˆμƒ)
      - name: Test with corrected config
        run: node test-mcp.js --config config-with-path.json

πŸ”¬ Simulating It Locally

1
2
3
4
5
# GUI ν™˜κ²½κ³Ό μœ μ‚¬ν•œ μ΅œμ†Œ PATH둜 ν…ŒμŠ€νŠΈ
env -i PATH=/usr/bin:/bin /bin/sh -c 'your-mcp-command'

# λ˜λŠ” Docker둜 κΉ¨λ—ν•œ ν™˜κ²½ ν…ŒμŠ€νŠΈ
docker run --rm -v $(pwd):/app alpine:latest /bin/sh -c 'cd /app && your-test'

Quick-Fix Checklist

⚑ Check Right Away

[ ] Run which uvx in the terminal β†’ note the path [ ] Check the GUI environment’s PATH: launchctl getenv PATH [ ] Check whether your MCP config has an env section

πŸ› οΈ Immediate Fix (5 Minutes)

[ ] Add env.PATH to the MCP config [ ] Or change command to an absolute path [ ] Restart Claude Desktop

πŸ—οΈ Complete Fix (30 Minutes)

[ ] Set PATH at the system level (plist file) [ ] Apply the same pattern to your other MCP servers [ ] Write test cases

πŸ‘₯ For Sharing With Your Team

[ ] Document an example claude_desktop_config.json [ ] Write an environment setup guide [ ] Standardize the common PATH values

🎯 Key Takeaways

  1. GUI apps have a different PATH from the terminal
  2. The **env** section of the MCP config is the safest fix
  3. An absolute path is a quick, temporary fix
  4. A system-level setting affects every GUI app

If this guide helped, please share it with colleagues struggling with the same problem! πŸš€

Additional Resources