The Complete Guide to Fixing MCP Server PATH Problems#
With a Focus on the “spawn uvx ENOENT” Error#
π Table of Contents#
- The Problem and Its Symptoms
- Root Cause Analysis
- Immediate Fixes
- Platform-Specific Notes
- Prevention for Developers
- Testing and Verification
- 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#
| Command | Typical install location | Reachable from GUI environment |
|---|
sh | /bin/sh | β
|
npx | /usr/local/bin/npx | β
|
uvx | ~/.local/bin/uvx | β |
cargo | ~/.cargo/bin/cargo | β |
π Option 1: Set PATH Explicitly in the env Section (Recommended)#
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:
βοΈ 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
|
π 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
`;
|
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
[ ] 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#
- GUI apps have a different PATH from the terminal
- The
**env** section of the MCP config is the safest fix - An absolute path is a quick, temporary fix
- A system-level setting affects every GUI app
If this guide helped, please share it with colleagues struggling with the same problem! π
Additional Resources#