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