mcp-nvm-bridge

mcp-nvm-bridge

Bridge to make MCP (Model Context Protocol) servers work seamlessly with NVM (Node Version Manager).

The Problem

When using NVM (Node Version Manager), MCP servers fail to run properly because:

• npx uses the wrong Node.js version
• Module resolution fails due to incorrect paths
• Environment variables from NVM aren't passed through
• The standard MCP installation instructions don't work

This affects millions of developers who use NVM for Node.js version management.

The Solution

mcp-nvm-bridge automatically detects NVM, resolves the correct paths, and bridges MCP servers to work perfectly with your NVM setup. No more manual configuration or path hunting!

Installation

npm install -g mcp-nvm-bridge

Usage

Basic Usage

Instead of struggling with paths, just use mcp-nvm-bridge:

# Run any MCP server through the bridge
mcp-nvm-bridge @modelcontextprotocol/server-filesystem /home

# With arguments
mcp-nvm-bridge @modelcontextprotocol/server-github --token YOUR_TOKEN

# Local servers work too
mcp-nvm-bridge ./my-local-server.js --port 3000

Generate Claude Desktop Configuration

Automatically generate the configuration file for Claude Desktop:

# Generate config for multiple servers
mcp-nvm-bridge --generate-config filesystem github memory

# This creates/updates the Claude Desktop config with proper paths

Quick Setup

Install and configure a server in one command:

# Install and configure the filesystem server
mcp-nvm-bridge --setup filesystem

# This will:
# 1. Install the server globally
# 2. Generate the configuration
# 3. Verify everything works

How It Works

1. Detects NVM - Checks multiple indicators to determine if NVM is active
2. Resolves Paths - Finds the correct Node.js, npm, and module paths
3. Bridges Execution - Spawns MCP servers with the proper environment
4. Preserves stdio - Maintains the exact stdio channels MCP requires

Configuration

Claude Desktop Configuration

After running --generate-config, your claude_desktop_config.json will contain:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-nvm-bridge",
      "args": ["@modelcontextprotocol/server-filesystem", "/home"]
    },
    "github": {
      "command": "mcp-nvm-bridge", 
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

Environment Variables

• MCP_NVM_DEBUG=true - Enable debug output
• MCP_NVM_SILENT=true - Suppress informational messages

Troubleshooting

Debug Mode

Run with debug output to see what's happening:

MCP_NVM_DEBUG=true mcp-nvm-bridge @modelcontextprotocol/server-filesystem

Common Issues

Server not found

• Make sure the server is installed: npm install -g @modelcontextprotocol/server-filesystem
• Or let npx handle it automatically

Permission denied

• Check file permissions: chmod +x your-server.js
• Make sure NVM has proper permissions

Still not working?

• Check NVM is active: nvm --version
• Try the debug mode above
• Open an issue with the debug output

Programmatic Usage

You can also use mcp-nvm-bridge programmatically:

const { bridge, isNVMActive, getNVMInfo } = require('mcp-nvm-bridge');

// Check if NVM is active
if (isNVMActive()) {
  console.log('NVM detected!');
  console.log(getNVMInfo());
}

// Bridge a server programmatically
const child = await bridge('@modelcontextprotocol/server-filesystem', ['/home']);

Supported Platforms

• ✅ macOS
• ✅ Linux
• ✅ WSL (Windows Subsystem for Linux)
• ❌ Windows (native) - NVM for Windows uses a different structure

How It Solves The Problem

Without mcp-nvm-bridge (Broken)

# This fails with NVM
npx @modelcontextprotocol/server-filesystem

# Error: Cannot find module...

With mcp-nvm-bridge (Working)

# This just works!
mcp-nvm-bridge @modelcontextprotocol/server-filesystem

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for details.

License

MIT © Harsh Joshi

Acknowledgments

• Thanks to Anthropic for creating the Model Context Protocol
• Thanks to the NVM project for Node.js version management
• Thanks to all developers who reported issues and helped test

Links

• GitHub Repository
• NPM Package
• Issue Tracker
• Model Context Protocol
• NVM Project