Skip to content

MCP Servers Don't Work with NVM #64

Closed

Description

@combdn

Problem

When using NVM (Node Version Manager), the standard installation and usage instructions for MCP servers don't work. The app tries to use an incorrect Node and fails.

Workaround

  1. Avoid npx, install packages globally.
  2. Use absolute paths to both the Node executable and server script.

Example:

{  
  "mcpServers": {
    "puppeteer": {
      "command": "/Users/username/.nvm/versions/node/v22.11.0/bin/node",
      "args": [
        "/Users/username/.nvm/versions/node/v22.11.0/lib/node_modules/@modelcontextprotocol/server-puppeteer/dist/index.js"
      ]
    }
  }
}

OS: macOS 15.1.1 (24B91)

Activity

  1. mckaywrigley commented on Nov 26, 2024

    @mckaywrigley

    I also ran into issues with the recommended npx setup, and I was able to successfully reproduce this workaround - fixes it completely.

    MCPs now install and attach correctly within Claude Desktop.

  2. lborgav commented on Nov 27, 2024

    @lborgav

    This workaround works fine

  3. adam91holt commented on Nov 27, 2024

    @adam91holt

    I can confirm this is working for me too.

    You may have a different node.js version installed so just do the following for puppeteer as an example

    npm i -g @modelcontextprotocol/server-puppeteer
    cd /Users/YOUR_USERNAME/.nvm/versions/node
    ls
    >>> v14.17.6        v16.19.0        v18.14.0        v18.20.4

    Then I ended up with this and it works sweet!

    {
      "mcpServers": {
        "puppeteer": {
          "command": "/Users/YOUR_USERNAME/.nvm/versions/node/v18.20.4/bin/node",
          "args": [
            "/Users/YOUR_USERNAME/.nvm/versions/node/v18.20.4/lib/node_modules/@modelcontextprotocol/server-puppeteer/dist/index.js"
          ]
        }
      }
    }
  4. jspahrsummers commented on Nov 27, 2024

    @jspahrsummers
    Member

    The challenge with NVM is that it seems to mostly work by installing a very complicated shell function into your shell profile. It'd be great if we could figure out your preferred Node version via NVM, but I haven't found a good way to do that—open to ideas!

  5. jspahrsummers commented on Nov 27, 2024

    @jspahrsummers
    Member

    Cross-linking: see #40 for Windows workaround steps as well

  6. unpinned this issue on Dec 3, 2024
  7. pinned this issue on Dec 3, 2024
  8. lolochka commented on Dec 4, 2024

    @lolochka

    Unfortunately, the issue is still reproducible on Mac with nvm installed.

    OS: macOS 15.1.1
    Claude: 0.7.5
    Locally I have checked that all packages are available with inputted paths.

    The SQlite server is working correctly, but tools for server-filesystem doesn't appear

    My settings

    {
      "mcpServers": {
        "sqlite": {
          "command": "uvx",
          "args": ["mcp-server-sqlite", "--db-path", "/Users/user/test.db"]
        },
        "filesystem": {
          "command": "/Users/user/.nvm/versions/node/v22.11.0/bin/node",
          "args": [
            "-y",
            "/Users/user/.nvm/versions/node/v22.11.0/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
            "/Users/user/claude"
          ]
        }
      }
    }
    
  9. mlaugharn commented on Dec 7, 2024

    @mlaugharn

    suggestion: the same way that there is the mcpServers field, can there also be an eg mcpShell field? Or maybe a shell or source key per individual server, eg "shell": "source /Users/user/mcp.sh" ? Might introduce 'too much' flexibility but it could make mcp more usable/transparent to tinker with.

  10. daaain commented on Dec 8, 2024

    @daaain

    I was struggling to get MCP working yesterday, the error messages in the logs were unhelpful, and the most confusing of all is that it just started working today. This might not be the repo for this request, but it would be really useful if it was explicily documented which shell Claude Desktop is using to start the MCP services.

    To your question @jspahrsummers, wouldn't nvm alias default work?

  11. jspahrsummers commented on Dec 9, 2024

    @jspahrsummers
    Member

    Unfortunately no, the environment for GUI apps is completely different from what you see on the command line.

  12. daaain commented on Dec 9, 2024

    @daaain

    Unfortunately no, the environment for GUI apps is completely different from what you see on the command line.

    Ah right, I had a look and to answer my own question, assuming that Claude Desktop's Electron implementation uses the MCP TS SDK, it's node:child_process spawn with shell: false.

  13. combdn commented on Dec 9, 2024

    @combdn
    Author

    In the meantime, I have migrated from NVM to mise, and now, if I start the Claude app from my shell (open -a Claude), it can correctly use node and npm (it didn’t work with NVM). That might be a workaround for some people with the same problem.

    PS Apple seems to have removed an option to set up the environment for the GUI apps through the launch agents. But I'm not sure. I didn’t dive too deep into it.

  14. 70 remaining items

  15. wrightkhlebisol commented on Jul 11, 2025

    @wrightkhlebisol

    Potentially easier workaround that I don't think has been mentioned yet--place a script somewhere like /usr/local/bin/npx-for-claude:
    #!/bin/zsh
    source ~/.zshrc
    exec npx "$@"
    Then chmod +x /usr/local/bin/npx-for-claude. Might need to riff on it if you use bash, but this works for me. Now I can do something like this in my config:
    {
    "mcpServers": {
    "everything": {
    "command": "npx-for-claude",
    "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
    }
    }
    Have only tested that this works with fnm. Not sure about nvm.

    This worked for me.

    Can you please check all versions installed in your NVM? do you have versions less than v18? if yes, try to delete them and run again. For some reasons Claude use the earliest version of node in NVM.

    Can confirm, uninstalling older node versions fixed it for me and I was able to setup the MCP with npx instead of global install

  16. added a commit that references this issue on Jul 15, 2025
  17. ahmetkca commented on Jul 30, 2025

    @ahmetkca

    Here is what works for me (with mise version manager):

    {
      "mcpServers": {
        "git": {
          "command": "mise",
          "args": [
          	"exec", "uv@latest", "--",
          	"uvx", "mcp-server-git"
          ],
          "env": {}
        },
        "fetch": {
          "command": "mise",
          "args": [
          	"exec", "uv@latest", "--",
          	"uvx", "mcp-server-fetch"
          ],
          "env": {}
        },
        "context7": {
          "command": "npx",
          "args": ["-y", "@upstash/context7-mcp@latest"]
        }
      }
    }
    
  18. olaservo commented on Aug 17, 2025

    @olaservo
    Member

    @claude could you take a look at the problems and solutions mentioned in this issue and then make a suggestion for what we could include in a troubleshooting guide, for when users encounter these problems when using nvm?

  19. claude commented on Aug 17, 2025

    @claude
    Contributor

    Claude finished @olaservo's task —— View job


    NVM Troubleshooting Guide Analysis Complete

    Based on the extensive discussion in this issue, here's my suggested content for a troubleshooting guide for NVM-related MCP server problems:

    Detailed Troubleshooting Guide Content

    NVM and Node Version Manager Troubleshooting

    Root Cause

    The primary issue occurs because GUI applications like Claude Desktop don't inherit shell environment variables that NVM requires. When Claude Desktop spawns MCP server processes, it uses spawn() with shell: false, meaning NVM's shell functions and PATH modifications aren't available.

    Common Error Messages

    • Error: spawn npx ENOENT
    • env: node: No such file or directory
    • command not found: node
    • Connection timeouts or MCP servers failing to start

    Diagnosis: Which Node Version is Claude Desktop Using?

    Add this temporary configuration to identify the problem:

    {
      "mcpServers": {
        "debug-node": {
          "command": "node",
          "args": ["-v"]
        }
      }
    }

    Check your MCP logs after restarting Claude Desktop. You might see Claude Desktop is using an old Node version (often the alphabetically first one in your NVM directory).

    Solution 1: Remove Old Node Versions (Simplest)

    Most effective solution mentioned by multiple users:

    1. List your installed Node versions:

      nvm list
    2. Remove versions older than Node 18:

      nvm uninstall v14.x.x
      nvm uninstall v16.x.x
      # Remove all old versions
    3. Keep only Node 18+ versions

    4. Restart Claude Desktop

    Why this works: Claude Desktop appears to use the alphabetically first Node version in the NVM directory. Removing old versions forces it to use a compatible version.

    Solution 2: Use Absolute Paths (Most Reliable)

    For maximum reliability, use absolute paths to both Node and the globally installed MCP server:

    1. Install MCP server globally:

      npm install -g @modelcontextprotocol/server-filesystem
    2. Find your Node version:

      nvm current
      # Example output: v22.11.0
    3. Configure with absolute paths:

      {
        "mcpServers": {
          "filesystem": {
            "command": "/Users/username/.nvm/versions/node/v22.11.0/bin/node",
            "args": [
              "/Users/username/.nvm/versions/node/v22.11.0/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
              "/path/to/directory"
            ]
          }
        }
      }

    Solution 3: Custom NPX Wrapper Script

    Create a wrapper script that sources your shell environment:

    1. Create /usr/local/bin/npx-for-claude:

      #!/usr/bin/env bash
      export NVM_DIR="$HOME/.nvm"
      [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
      nvm use default > /dev/null
      exec npx "$@"
    2. Make executable:

      chmod +x /usr/local/bin/npx-for-claude
    3. Configure Claude Desktop:

      {
        "mcpServers": {
          "filesystem": {
            "command": "npx-for-claude",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
          }
        }
      }

    Solution 4: PATH Environment Variable

    Set explicit PATH in the MCP configuration:

    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
          "env": {
            "PATH": "/Users/username/.nvm/versions/node/v22.11.0/bin:/bin"
          }
        }
      }
    }

    Solution 5: Shell Command Wrapper

    Use a shell to execute the command:

    {
      "mcpServers": {
        "filesystem": {
          "command": "bash",
          "args": [
            "-c",
            "source $HOME/.nvm/nvm.sh && nvm use default && npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
          ]
        }
      }
    }

    Alternative Version Managers

    Similar solutions work for other version managers:

    For fnm:

    #!/usr/bin/env bash
    fnm exec --using=default npx "$@"

    For mise:

    {
      "command": "mise",
      "args": ["exec", "node@latest", "--", "npx", "-y", "@mcp-server"]
    }

    For volta:
    Use volta which node and volta which [package] to find paths, then use absolute paths.

    Verification Steps

    1. Check MCP logs at:

      • macOS: ~/Library/Logs/Claude/
      • Logs should show successful server initialization
    2. Verify in Claude Desktop:

      • Look for MCP server tools in the attachment menu
      • Test basic server functionality

    When Solutions Don't Work

    • Ensure you're restarting Claude Desktop after configuration changes
    • Verify file paths exist and are accessible
    • Check MCP server logs for specific error messages
    • Try installing the MCP server globally first (npm install -g [package])
    • Consider switching to a different Node version manager (mise is mentioned as working better than NVM)

    Permanent Solution Recommendation

    For the best long-term experience:

    1. Remove old Node versions (< 18) from NVM
    2. Use absolute paths for critical MCP servers
    3. Consider switching to mise as it handles GUI application environments better than NVM

    Todo List:

    • Review all comments to understand the core problems
    • Categorize different types of issues and their root causes
    • Identify the most reliable workarounds from user feedback
    • Create structured troubleshooting guide content
    • Provide clear step-by-step solutions

    This troubleshooting guide covers all the major solutions mentioned in the issue, organized from simplest to most complex, with clear explanations of why each approach works.


  20. olaservo commented on Aug 17, 2025

    @olaservo
    Member

    @domdomegg do you think troubleshooting docs like what Claude suggested above ^^ should go in this repo, or perhaps in the main MCP documentation instead?

  21. ifokeev commented on Aug 18, 2025

    @ifokeev

    Thanks, @olaservo, your insight was really helpful for debugging the problem. The issue was with the node executable path. Here's a workaround:

    {
      "mcpServers": {
        "filesystem": {
          "command": "bash",
          "args": [
            "-c",
            "export PATH=/Users/user/.nvm/versions/node/v22.14.0/bin:$PATH && npx -y @modelcontextprotocol/server-filesystem /Users/user/Code"
          ]
        }
      }
    }
    
  22. benknight commented on Oct 4, 2025

    @benknight

    This would appear to be an extremely common issue given the likelihood of Node developers needing to use NVM to manage multiple versions of Node across their projects. Uninstalling the earlier versions of Node is a temporary solution but not permanent since the larger issue is that the version of Node Claude chooses to user when firing the MCP server command is unpredictable and the same issue could reappear.

    Checking the macOS client logs, why is the "paths" array that gets resolved in this order to begin with?

    2025-10-04T05:03:12.330Z [Readwise MCP] [info] Using MCP server command: /Users/ben/.nvm/versions/node/v18.18.2/bin/npx with args and path: {
      metadata: {
        args: [ '-y', '@readwise/readwise-mcp', [length]: 2 ],
        paths: [
          '/Users/ben/.nvm/versions/node/v18.18.2/bin',
          '/Users/ben/.nvm/versions/node/v18.20.7/bin',
          '/Users/ben/.nvm/versions/node/v20.13.0/bin',
          '/Users/ben/.nvm/versions/node/v20.17.0/bin',
          '/Users/ben/.nvm/versions/node/v20.9.0/bin',
          '/Users/ben/.nvm/versions/node/v22.14.0/bin',
          '/usr/local/bin',
          '/opt/homebrew/bin',
          '/opt/local/bin',
          '/usr/bin',
          '/usr/bin',
          '/bin',
          '/usr/sbin',
          '/sbin',
          [length]: 14
        ]
      }
    }
    

    This path array looks to not be based on the user's $PATH but embedded into the Claude source. It would probably make sense to reverse the order of NVM versions so that the most recent version resolved first. Correct me if I'm wrong.

  23. olaservo commented on Oct 29, 2025

    @olaservo
    Member

    Going to close this issue since its not really a server bug and these comments will still be discoverable in GitHub when the issue is closed. Thanks everyone for the comments and suggestions to help resolve this.

  24. Ishannaik commented on Mar 26, 2026

    @Ishannaik

    2026 update: definitive Windows + nvm-windows fix

    Still hitting this in 2026 with nvm-windows (nvm4w), Node v24.8.0, and Claude Code CLI. The failure is completely silent — ✗ Failed to connect, no errors, server even logs "connected" but never responds on stdout.

    Quick diagnostic: If claude mcp list shows .exe-based MCPs working but all npx-based ones failing — you're hitting this.

    Fix: Global install + absolute paths in config:

    npm install -g <package>@latest
    where node    # e.g. C:\nvm4w\nodejs\node.exe
    npm root -g   # e.g. C:\Users\<YOU>\AppData\Roaming\npm\node_modules
    {
      "command": "C:\nvm4w\nodejs\node.exe",
      "args": ["C:\Users\<YOU>\AppData\Roaming\npm\node_modules\<pkg>\<bin-entry>.js", ...]
    }

    This bypasses the .cmd shim and nvm PATH issues entirely. C:\nvm4w\nodejs\node.exe is nvm-windows' symlink that auto-updates on nvm use.

    Full writeup with root cause analysis + manual handshake verification: ChromeDevTools/chrome-devtools-mcp#182

  25. Sinmson commented on Aug 5, 2026

    @Sinmson

    For everyone finding this, i solved it with this little trick:

    {
      "mcpServers": {
        "angular-cli": {
          "command": "bash",
          "args": [
            "~/.nvm/nvm-exec",
            "npx",
            "@angular/cli",
            "mcp"
          ]
        }
      }
    }
  26. lajiaojiang-ai commented on Aug 15, 2026

    @lajiaojiang-ai

    NVM is still a common reason Desktop/GUI clients show a configured MCP server with zero tools: the GUI process cannot see the nvm npx shim.

    I added a local diagnostic that flags this case, plus the related Windows npx spawn issue from #40:

    https://github.com/lajiaojiang-ai/mcp-why

    Not a replacement for putting a real Node path in the config. It just names the failure instead of leaving people to guess.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions