Setup Unbrowser Local

Get Claude Desktop browsing the web intelligently in under 5 minutes. Follow the guide for your platform below.

Node.js 20+ Required

Unbrowser requires Node.js version 20 or later. Older versions will fail with a "File is not defined" error. Follow the instructions below to ensure you have the correct version.

1 Install Node.js 20+

First, ensure you have Node.js 20 or later installed. Check your current version:

Terminal
node --version

If you see v18 or earlier, install Node.js 20+ using one of these methods:

Recommended Using Homebrew
Terminal
# Install or update Node.js brew install node@22 # Add to PATH (add this to ~/.zshrc) export PATH="/opt/homebrew/opt/node@22/bin:$PATH" # Restart terminal or run: source ~/.zshrc
Alternative Using nvm (Node Version Manager)
Terminal
# Install nvm if you don't have it curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # Restart terminal, then install Node 22 nvm install 22 nvm use 22 nvm alias default 22

2 Install Unbrowser

Install Unbrowser globally so it's available system-wide:

Terminal
npm install -g @unbrowser/local

Verify the installation:

Terminal
# This should show the path to unbrowser which unbrowser

3 Configure Claude Desktop

Open your Claude Desktop configuration file. The location depends on your setup:

Terminal
# Open the config file in your editor open ~/Library/Application Support/Claude/claude_desktop_config.json # Or create it if it doesn't exist mkdir -p ~/Library/Application Support/Claude touch ~/Library/Application Support/Claude/claude_desktop_config.json open ~/Library/Application Support/Claude/claude_desktop_config.json

Add the Unbrowser MCP server configuration. Important: Use the full path to Node.js to avoid version conflicts.

Find your Node.js path: Run which node in Terminal and use that path in the config below.
Recommended With explicit Node.js path (avoids version conflicts)
{ "mcpServers": { "unbrowser": { "command": "/opt/homebrew/opt/node@22/bin/node", "args": ["/opt/homebrew/lib/node_modules/@unbrowser/local/dist/index.js"] } } }
Alternative Using npx (simpler but requires correct Node in PATH)
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }
Using nvm or asdf? Your shell config may set a different Node version. Use the explicit path method above, replacing the path with the output of: nvm which 22 or asdf which node

4 Restart Claude Desktop

Quit Claude Desktop completely and reopen it. The Unbrowser tools should now be available.

Test it: Ask Claude "Can you browse https://news.ycombinator.com and tell me the top stories?"

1 Install Node.js 20+

First, check if you have Node.js 20+ installed:

PowerShell
node --version

If you see v18 or earlier, install Node.js 22:

Recommended Download from nodejs.org

Download and run the installer from nodejs.org. Choose the LTS version (22.x).

Alternative Using winget
PowerShell (Admin)
winget install OpenJS.NodeJS.LTS
Alternative Using nvm-windows
PowerShell (Admin)
# Download nvm-windows from: # https://github.com/coreybutler/nvm-windows/releases # After installing nvm-windows: nvm install 22 nvm use 22
Important: After installing, close and reopen PowerShell/Terminal to refresh your PATH.

2 Install Unbrowser

Open PowerShell and install Unbrowser globally:

PowerShell
npm install -g @unbrowser/local

Verify the installation:

PowerShell
# Find where npm installed unbrowser npm root -g

3 Configure Claude Desktop

Open your Claude Desktop configuration file:

PowerShell
# Open the config directory explorer "%APPDATA%\Claude" # Create config file if it doesn't exist if (!(Test-Path "$env:APPDATA\Claude")) { mkdir "$env:APPDATA\Claude" } notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add the Unbrowser MCP server configuration:

Recommended With explicit paths (avoids version conflicts)
{ "mcpServers": { "unbrowser": { "command": "C:\\Program Files\\nodejs\\node.exe", "args": ["C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\@unbrowser\\local\\dist\\index.js"] } } }
Replace YOUR_USERNAME with your Windows username. You can find the exact path by running: npm root -g
Alternative Using npx (simpler but requires correct Node in PATH)
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

4 Restart Claude Desktop

Close Claude Desktop completely (check the system tray) and reopen it.

Test it: Ask Claude "Can you browse https://news.ycombinator.com and tell me the top stories?"

1 Install Node.js 20+

First, check your current Node.js version:

Terminal
node --version

If you see v18 or earlier, install Node.js 22:

Recommended Using nvm (works on all distros)
Terminal
# Install nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # Restart terminal or run: source ~/.bashrc # or ~/.zshrc # Install Node 22 nvm install 22 nvm use 22 nvm alias default 22
Alternative Ubuntu/Debian using NodeSource
Terminal
# Add NodeSource repository curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # Install Node.js sudo apt-get install -y nodejs
Alternative Fedora/RHEL
Terminal
# Add NodeSource repository curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - # Install Node.js sudo dnf install -y nodejs

2 Install Unbrowser

Install Unbrowser globally:

Terminal
npm install -g @unbrowser/local
Permission denied? If you get EACCES errors, either use nvm (recommended) or configure npm to use a different directory: npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.

Verify the installation:

Terminal
which unbrowser # Should output something like: /home/user/.nvm/versions/node/v22.x.x/bin/unbrowser

3 Configure Claude Desktop

Open your Claude Desktop configuration file:

Terminal
# Create config directory if needed mkdir -p ~/.config/Claude # Open config file nano ~/.config/Claude/claude_desktop_config.json # Or use: code, vim, gedit, etc.

Add the Unbrowser MCP server configuration. First, find your paths:

Terminal
# Get your Node.js path which node # Get your npm global modules path npm root -g
Recommended With explicit paths (example using nvm)
{ "mcpServers": { "unbrowser": { "command": "/home/YOUR_USER/.nvm/versions/node/v22.12.0/bin/node", "args": ["/home/YOUR_USER/.nvm/versions/node/v22.12.0/lib/node_modules/@unbrowser/local/dist/index.js"] } } }
Alternative Using npx (simpler but requires correct Node in PATH)
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

4 Restart Claude Desktop

Close and reopen Claude Desktop.

Test it: Ask Claude "Can you browse https://news.ycombinator.com and tell me the top stories?"

Configuration for Other AI Tools

Already completed the steps above? Here's how to configure Unbrowser for other AI coding tools.

Claude Code (CLI)

Claude Code uses MCP servers defined in your settings. Run this command:

Terminal
claude mcp add unbrowser npx @unbrowser/local

Or add manually to your settings file:

~/.claude/settings.json
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }
Version conflicts? Use explicit paths like in the Claude Desktop instructions above.

Cursor

Cursor supports MCP servers via its settings. Open Settings (Cmd/Ctrl + ,) and add to your config:

Cursor Settings (JSON)
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

Or with explicit Node.js path (recommended for version managers):

Cursor Settings (JSON)
{ "mcpServers": { "unbrowser": { "command": "/path/to/node", "args": ["/path/to/node_modules/@unbrowser/local/dist/index.js"] } } }
Find your paths: Run which node and npm root -g to get the correct paths for your system.

Windsurf (Codeium)

Windsurf supports MCP servers through its Cascade AI. Add to your MCP configuration:

~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

Restart Windsurf after adding the configuration.

Warp Terminal

Warp's AI features support MCP servers. Add to your Warp MCP config:

~/.warp/mcp.json
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

Restart Warp after adding the configuration.

Continue (VS Code Extension)

Continue supports MCP servers in its configuration. Add to your Continue config:

~/.continue/config.json
{ "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "npx", "args": ["@unbrowser/local"] } } ] } }

Reload VS Code after adding the configuration.

Other MCP-Compatible Tools

Any tool that supports the Model Context Protocol (MCP) can use Unbrowser. The general pattern is:

Generic MCP Configuration
{ "mcpServers": { "unbrowser": { "command": "npx", "args": ["@unbrowser/local"] } } }

For tools with version manager conflicts, use explicit paths:

With Explicit Paths
{ "mcpServers": { "unbrowser": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/node_modules/@unbrowser/local/dist/index.js"] } } }
Compatible tools include: Zed, Amazon Q Developer, Cline, Roo Code, Sourcegraph Cody, and any other MCP-compatible AI assistant.

Verify Your Setup

Troubleshooting

"File is not defined" or "ReferenceError: File is not defined"

This error means Node.js 18 or earlier is being used instead of Node.js 20+.

Solution: Use the explicit Node.js path method in your Claude Desktop config. Run which node to find your Node 22 path and update the config to use that exact path.

"command not found: unbrowser" or "unbrowser is not recognized"

The global npm package isn't in your PATH, or wasn't installed correctly.

Solution: Reinstall with npm install -g @unbrowser/local. If using nvm, make sure you're using the correct Node version first. Then use the explicit path method in your config.

Claude Desktop doesn't show Unbrowser tools

The config file might have syntax errors or Claude Desktop needs a full restart.

Solution: 1) Validate your JSON at jsonlint.com. 2) Quit Claude Desktop completely (check system tray on Windows). 3) Reopen and try again.

Still having issues?

Check the Claude Desktop logs or run unbrowser manually to see errors.

Debug: Run node /path/to/unbrowser/dist/index.js in your terminal to see startup errors. You can also check Claude Desktop's developer console.