Bug: Claude Desktop uses incorrect Node.js version, causing "File is not defined" crash

[bencium]

Environment

• OS: macOS (Darwin 25.1.0, Apple Silicon M2)
• Claude Desktop: Latest version
• mcp-remote: 0.1.31 (latest)
• Node.js versions installed:
  • nvm: v18.15.0, v18.17.0, v20.18.0, v20.19.6
  • Homebrew: v25.2.1

Problem

When configuring mcp-remote in Claude Desktop's claude_desktop_config.json, the MCP server
crashes immediately with:

ReferenceError: File is not defined
at Object. (/Users/.../.npm/_npx/.../node_modules/undici/lib/web/webidl/index.js:531:48)
...
Node.js v18.15.0

Root Cause

Claude Desktop constructs its own PATH with nvm Node versions taking precedence:

paths: [
'/Users/.../.nvm/versions/node/v18.15.0/bin', // ← Node 18 first
'/Users/.../.nvm/versions/node/v18.17.0/bin',
'/Users/.../.nvm/versions/node/v20.18.0/bin',
...
'/opt/homebrew/bin', // ← Node 25 comes later
]

Even when specifying the full path to npx (/opt/homebrew/bin/npx), the spawned process inherits
this PATH and runs under Node 18.

The undici package (dependency of mcp-remote) requires Node 20+ because the File global was
added in Node 20.

Configuration Tested (all failed)

// Attempt 1: Default
{
  "command": "npx",
  "args": ["-y", "mcp-remote@latest", "https://example.com/mcp"]
}

// Attempt 2: Full path to npx
{
  "command": "/opt/homebrew/bin/npx",
  "args": ["-y", "mcp-remote@latest", "https://example.com/mcp"]
}

// Attempt 3: env override (ignored by Claude Desktop)
{
  "command": "/opt/homebrew/bin/npx",
  "args": ["-y", "mcp-remote@latest", "https://example.com/mcp"],
  "env": {
    "PATH": "/opt/homebrew/bin:/usr/bin:/bin"
  }
}

Workaround

Created a wrapper script that explicitly sets PATH before executing:

# ~/.local/bin/mcp-remote-wrapper
#!/bin/bash
export PATH="/opt/homebrew/bin:$PATH"
exec /opt/homebrew/bin/npx -y mcp-remote@latest "$@"

Then in config:
{
  "command": "/Users/username/.local/bin/mcp-remote-wrapper",
  "args": ["https://example.com/mcp"]
}

Expected Behavior

Either:
1. mcp-remote should fail gracefully with a clear error message about Node version requirements
2. Claude Desktop should respect the env configuration option
3. Documentation should warn about nvm PATH conflicts

Suggested Fix

Add a Node.js version check at startup in mcp-remote:

const [major] = process.versions.node.split('.').map(Number);
if (major < 20) {
  console.error(`mcp-remote requires Node.js 20+. Current version: ${process.version}`);
  process.exit(1);
}

Related

- The MCP server (Lex API) uses Streamable HTTP transport which works correctly
- Claude Code's native --transport http works fine (no mcp-remote needed)
- Issue only affects Claude Desktop users with nvm installed