NVM MCP Server for Antigravity

An MCP server that wraps NVM (Node Version Manager), giving Antigravity agents full control over Node.js versions — without needing Node or npm to already be on $PATH.

Why this exists

Antigravity agents run in a non-interactive subprocess and never source your shell's .zshrc / .bashrc. Because NVM adds Node to $PATH only in interactive shells, agents can't find node or npm. This server sources nvm.sh directly before every command, completely bypassing the $PATH problem.

Requirements

Python 3.10+
NVM installed at ~/.nvm (or set NVM_DIR in the config)
pip install mcp (or pip install -r requirements.txt)

Installation

# 1. Clone / copy this folder somewhere permanent
cp -r nvm-mcp-server ~/.nvm-mcp-server

# 2. Install the one dependency
pip install -r ~/.nvm-mcp-server/requirements.txt
# Or, if you prefer a venv:
python3 -m venv ~/.nvm-mcp-server/.venv
~/.nvm-mcp-server/.venv/bin/pip install mcp

Antigravity Configuration

Open (or create) ~/.gemini/antigravity/mcp_config.json and add:

{
  "mcpServers": {
    "nvm-manager": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/.nvm-mcp-server/nvm_server.py"],
      "env": {
        "NVM_DIR": "/Users/YOUR_USERNAME/.nvm"
      }
    }
  }
}

Venv users: replace "python3" with the absolute path to the venv Python, e.g. "/Users/YOUR_USERNAME/.nvm-mcp-server/.venv/bin/python3".

Restart Antigravity after saving the config. The nvm-manager server will appear under MCP Servers.

Available Tools

Tool	What it does
`nvm_list`	List all locally installed Node versions
`nvm_list_remote`	List versions available to install (accepts filter: `'lts'`, `'22'`, etc.)
`nvm_install`	Download and install a version (`'22'`, `'lts'`, `'lts/iron'`, `'20.11.0'`)
`nvm_use`	Switch the session-active version — persists for all subsequent calls
`nvm_current`	Show which version is currently active in the session
`nvm_alias`	Set an NVM alias, e.g. point `default` at a new version
`node_run`	Run `node <args>` with the active (or a specified) version
`npm_run`	Run `npm <args>` with the active (or a specified) version
`npx_run`	Run `npx <args>` with the active (or a specified) version

All three runner tools accept an optional version field that overrides the session-active version for that one call, and an optional cwd field.

Example agent workflow

Agent: nvm_list           → sees v20.11.0 and v22.3.0 installed
Agent: nvm_use "22"       → session set to Node 22
Agent: npm_run "install"  → runs npm install under Node 22
Agent: node_run "index.js" → runs the script under Node 22

# Need a version that isn't installed yet?
Agent: nvm_install "lts"  → downloads latest LTS
Agent: nvm_use "lts"      → switches to it
Agent: nvm_alias "default" "lts"  → makes it the permanent default

Custom NVM location

If NVM is installed somewhere other than ~/.nvm, set NVM_DIR in the env block of mcp_config.json:

"env": {
  "NVM_DIR": "/opt/homebrew/opt/nvm"
}

Troubleshooting

Symptom	Fix
`nvm.sh not found`	Verify `NVM_DIR` in the `env` block points to your NVM root
`nvm_install` times out	Increase the subprocess timeout in `nvm_server.py` (default 300 s)
Version not found	Run `nvm_list_remote` to check the exact version string
Server not appearing	Check Antigravity → `...` → MCP Servers for error messages

NVM MCP Server