How to Set Up Unbrowse MCP Server for Claude Desktop

This guide walks through installing Unbrowse, configuring it as an MCP server for Claude Desktop, and testing it with real website resolves. By the end, your Claude Desktop will have a fast, API-native web browsing tool that caches routes for instant repeat access.

What You Are Setting Up

Unbrowse is an API-native agent browser. Instead of rendering web pages, it discovers the internal APIs behind websites and calls them directly. As an MCP server, it gives Claude Desktop five core tools:

• unbrowse_resolve -- Find cached API routes for a website and return structured data
• unbrowse_execute -- Call a specific endpoint with extraction and filtering
• unbrowse_search -- Search the shared marketplace for routes other agents have discovered
• unbrowse_login -- Authenticate with a website through an interactive browser window
• unbrowse_health -- Check server status

First visits to a site take 20-80 seconds (Unbrowse captures traffic and indexes the APIs). Every subsequent visit resolves from cache in under 200 milliseconds.

Prerequisites

• macOS, Linux, or Windows (with WSL for Windows)
• Git installed
• Node.js 18+ installed
• Claude Desktop installed and running
• Chrome or Firefox installed (Unbrowse extracts cookies from your browser for authentication)

Step 1: Install Unbrowse

Open your terminal and run:

git clone --single-branch --depth 1 https://github.com/unbrowse-ai/unbrowse.git ~/unbrowse
cd ~/unbrowse && ./setup --host mcp

This does several things:

1. Clones the Unbrowse repository
2. Installs dependencies
3. Prebuilds the CLI runtime
4. Installs the unbrowse command globally
5. Runs first-time setup (Terms of Service acceptance, agent registration)
6. Writes the MCP configuration file

What Happens During First-Time Setup

The setup script will prompt you for:

• Terms of Service acceptance -- Confirms you will not use Unbrowse to attack or abuse target sites, and that discovered API routes may be shared in the marketplace
• Agent email -- An email-style identity for your agent registration (used for marketplace attribution)
• Wallet setup (optional) -- If you want to earn from route mining, you can configure a Crossmint lobster.cash wallet

For a quick setup without wallet configuration:

cd ~/unbrowse && ./setup --host mcp --accept-tos --agent-email you@example.com --skip-wallet-setup

Verify Installation

After setup completes, verify Unbrowse is working:

unbrowse health

You should see a JSON response with server status, version, and uptime. The server runs on http://localhost:6969 by default.

Step 2: Configure Claude Desktop

The setup script writes an MCP config to ~/.config/unbrowse/mcp/unbrowse.json. You need to add this to Claude Desktop's configuration.

Locate Your Claude Desktop Config

Claude Desktop's MCP configuration file is at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

If the file does not exist, create it.

Add Unbrowse as an MCP Server

Open claude_desktop_config.json and add the Unbrowse server entry. You can find the exact config in the generated file, but here is the standard configuration:

{
  "mcpServers": {
    "unbrowse": {
      "command": "unbrowse",
      "args": ["mcp"]
    }
  }
}

If you have other MCP servers configured, add the unbrowse entry alongside them:

{
  "mcpServers": {
    "unbrowse": {
      "command": "unbrowse",
      "args": ["mcp"]
    },
    "other-server": {
      "command": "npx",
      "args": ["other-mcp-server"]
    }
  }
}

A generic template is also available at unbrowse.ai/mcp.json if you prefer to start from the published config.

Restart Claude Desktop

After saving the config file, fully quit and restart Claude Desktop. The Unbrowse MCP server should appear in the list of available tools.

Step 3: Test with Example Resolves

Open a new conversation in Claude Desktop and try these test queries.

Test 1: Simple Website Resolve

Ask Claude:

"Use Unbrowse to find out what API endpoints are available on Hacker News."

Claude will call unbrowse_resolve with the intent and URL. If Hacker News routes are already in the marketplace (likely, given it is a popular site), you will get cached results in under a second. If not, Unbrowse will capture and index the site.

You should see a response with available_endpoints listing the discovered API routes, each with descriptions, schema summaries, and sample values.

Test 2: Search with Parameters

Ask Claude:

"Use Unbrowse to search for 'AI agents' on Google."

This tests parameter binding. Unbrowse resolves the Google search endpoint, substitutes the query parameter, and returns structured search results.

Test 3: Authenticated Site

Ask Claude:

"Use Unbrowse to get my GitHub notifications."

If you are logged into GitHub in Chrome, Unbrowse extracts your cookies automatically and accesses the authenticated API. If cookies are not available, it will prompt you to log in via unbrowse_login.

Test 4: Browse and Index a New Site

Ask Claude:

"Use Unbrowse to find restaurant listings on yelp.com for San Francisco."

If Yelp has not been indexed yet, Unbrowse will open a browser session, navigate the site, capture traffic, and index the APIs. This first-time capture takes 20-80 seconds. After indexing, future Yelp queries from any conversation will resolve from cache.

Step 4: Understand the Output

When Unbrowse resolves a site, the response includes:

• available_endpoints -- List of discovered API endpoints, sorted by relevance score
• description -- What each endpoint returns
• schema_summary -- Nested response structure (3 levels deep)
• sample_values -- Concrete example values from captured data
• input_params -- Required and optional parameters with types and examples
• action_kind -- The type of action (search, list, detail, timeline)
• dom_extraction -- Whether the data comes from a real API call (false) or page HTML extraction (true)

Prefer endpoints where dom_extraction is false -- these are real API calls that are faster and more reliable than HTML scraping.

Troubleshooting

Unbrowse Server Not Starting

If Claude Desktop cannot connect to Unbrowse:

1. Check if the server is running: unbrowse health
2. If not running, start it manually: unbrowse health (the CLI auto-starts the server)
3. Check the port is not in use: lsof -i :6969
4. Check logs: tail -f ~/.unbrowse/logs/unbrowse-$(date +%F).log

Stale Server Process

If you recently updated Unbrowse but the old version seems to be running:

pkill -9 -f 'unbrowse|kuri'
sleep 2
unbrowse health

This kills any stale processes and starts a fresh server.

Authentication Not Working

If Unbrowse cannot access authenticated sites:

1. Make sure you are logged into the site in Chrome or Firefox
2. Close and reopen the terminal (cookie DB access sometimes needs a fresh session)
3. Try explicit login: ask Claude to "use Unbrowse to log into [site]"
4. Check that Chrome is not running with a custom profile that Unbrowse cannot find

Empty Results After Capture

If Unbrowse captures a site but returns no endpoints:

• The site may use anti-bot protections that block headless browsers
• SPAs that load data lazily may need interaction (scrolling, clicking) to trigger API calls
• Try asking Claude to browse the site interactively: "Use Unbrowse to go to [url], then take a snapshot and look around"

Configuration Options

Environment Variables

Variable	Default	Description
PORT	6969	Server port
HOST	127.0.0.1	Server bind address
UNBROWSE_URL	http://localhost:6969	Base URL for the skill
UNBROWSE_API_KEY	(auto-generated)	Marketplace API key

Data Directories

All Unbrowse data is stored under ~/.unbrowse/:

Path	Contents
~/.unbrowse/config.json	Agent credentials and API key
~/.unbrowse/profiles/<domain>/	Browser profiles (cookies, sessions)
~/.unbrowse/skill-snapshots/	Cached skill manifests
~/.unbrowse/route-cache.json	Intent-to-route cache (24h TTL)
~/.unbrowse/logs/	Daily debug logs

Upgrading

Unbrowse does not self-update. To upgrade after a new release:

cd ~/unbrowse
git pull --ff-only
./setup --host mcp

Then restart Claude Desktop to pick up the new version.

Using Unbrowse with Other Agent Hosts

While this guide focuses on Claude Desktop, Unbrowse works with any MCP-compatible agent host:

• Cursor: Add the same MCP config to Cursor's settings
• Claude Code: Run cd ~/unbrowse && ./setup --host mcp and the config is auto-detected
• Codex: Run cd ~/.codex/skills/unbrowse && ./setup --host codex
• Windsurf: Add the MCP config to Windsurf's MCP settings
• Open Code: Run ./setup --host off and register the /unbrowse command

The Unbrowse MCP server is identical across all hosts. The only difference is where the configuration file goes.

What Happens Next

Once Unbrowse is set up, every website your agent visits gets indexed. Routes are cached locally and shared to the marketplace. Over time, your agent builds a growing library of API routes that make web access faster.

The shared marketplace means you also benefit from routes discovered by other agents. Popular sites like Google, GitHub, Reddit, and LinkedIn likely already have cached routes available, giving you instant access from day one.

For the full technical details, read the paper: Internal APIs Are All You Need (Tham, Garcia & Hahn, 2026).

Need help? Join the Discord: discord.gg/VWugEeFNsG