unbrowse-mcp

Unbrowse MCP

The Internet-Use layer for AI Agents - A Model Context Protocol (MCP) server that enables AI to interact with websites at the network level.

Why Unbrowse?

Current AI browser automation is slow, unreliable, and expensive. Unbrowse provides:

• 50x faster - Execute actions in <2 seconds vs 5-60 seconds
• 90%+ reliability - Compared to 70-85% with browser automation
• 20-50x cost reduction - $0.001-$0.006 per operation
• Universal coverage - Works with most websites, not just the ~1% with APIs

Documentation

Full documentation is available at getfoundry.gitbook.io/unbrowse

Quick Start

Installation

# Run directly with npx
npx unbrowse-mcp

# Or install globally
npm install -g unbrowse-mcp

Via Smithery

npx -y @smithery/cli install @lekt9/unbrowse-mcp

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "unbrowse": {
      "command": "npx",
      "args": ["unbrowse-mcp"],
      "env": {
        "SOLANA_PRIVATE_KEY": "your_base58_encoded_private_key"
      }
    }
  }
}

Authentication Options

Choose one of three authentication methods:

Option 1: x402 Payment Mode (Recommended)

Use a Solana wallet with USDC - no account or API key required. Just fund your wallet and go:

export SOLANA_PRIVATE_KEY="your_base58_encoded_private_key"
export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"  # optional

Pricing: 0.1 cents per search, 0.5 cents per execution

Option 2: API Key

Get your API key from unbrowse.ai:

export UNBROWSE_API_KEY="re_xxxxxxxxxxxxx"

Option 3: Session Token

Use a session token from browser cookies:

export UNBROWSE_SESSION_TOKEN="cm4xxxxxxxxxxxxx"

x402 API Endpoints

The x402 protocol enables pay-per-request API access using Solana USDC. No API key required - just a funded wallet.

Base URL: https://index.unbrowse.ai

Search Abilities

GET /x402/abilities?q={query}&limit={limit}

Cost: 0.1 cents (1000 USDC lamports)

Parameters:

• q - Search query (required)
• limit - Max results (default: 12, max: 45)

Execute Ability

POST /x402/abilities/{abilityId}/execute

Cost: 0.5 cents (5000 USDC lamports) - Split: 20% platform, 80% ability owner

Body:

{
  "params": { "key": "value" },
  "transformCode": "(data) => data.results"  // optional
}

Protocol Flow

• Request - Client makes request to x402 endpoint
• 402 Response - Server responds with payment requirements:

  {
    "error": "Payment required",
    "payment": {
      "type": "usdc",
      "network": "solana",
      "chain": "mainnet-beta",
      "recipient": "PLATFORM_WALLET",
      "amount": "1000",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "splits": [
        { "recipient": "PLATFORM", "amount": "200", "percentage": 20 },
        { "recipient": "OWNER", "amount": "800", "percentage": 80 }
      ]
    }
  }
  

• Payment - Client constructs and signs USDC transfer transaction
• Retry - Client retries with X-Payment header:

  X-Payment: base64({ "transaction": "<base64_signed_tx>" })
  

• Process - Server verifies payment, submits transaction, returns result

Example Integration (Node.js)

import { Connection, Keypair, Transaction } from "@solana/web3.js";
import { createTransferInstruction, getAssociatedTokenAddress } from "@solana/spl-token";
import bs58 from "bs58";

const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

async function searchWithPayment(query, privateKey) {
  const keypair = Keypair.fromSecretKey(bs58.decode(privateKey));

  // 1. Make initial request
  let response = await fetch(`https://index.unbrowse.ai/x402/abilities?q=${query}`);

  if (response.status !== 402) return response.json();

  // 2. Parse payment requirement
  const { payment } = await response.json();

  // 3. Build USDC transfer transaction
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const tx = new Transaction();

  for (const split of payment.splits) {
    const fromAta = await getAssociatedTokenAddress(new PublicKey(USDC_MINT), keypair.publicKey);
    const toAta = await getAssociatedTokenAddress(new PublicKey(USDC_MINT), new PublicKey(split.recipient));
    tx.add(createTransferInstruction(fromAta, toAta, keypair.publicKey, BigInt(split.amount)));
  }

  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  tx.feePayer = keypair.publicKey;
  tx.sign(keypair);

  // 4. Retry with payment header
  const paymentHeader = Buffer.from(JSON.stringify({
    transaction: tx.serialize().toString("base64")
  })).toString("base64");

  response = await fetch(`https://index.unbrowse.ai/x402/abilities?q=${query}`, {
    headers: { "X-Payment": paymentHeader }
  });

  return response.json();
}

Available Tools

Tool	Description
search_abilities	Search for indexed web abilities using natural language
execute_abilities	Execute multiple abilities in parallel
search_abilities_parallel	Run multiple searches simultaneously
ingest_api_endpoint	Index new API endpoints (optional)
get_payment_history	View x402 payment history (x402 mode only)

Environment Variables

# Authentication (choose ONE)
SOLANA_PRIVATE_KEY=your_base58_key  # x402 pay-per-request (recommended)
UNBROWSE_API_KEY=re_xxxxxxxxxxxxx   # API key auth
UNBROWSE_SESSION_TOKEN=cm4xxxxxxx   # Session token auth

# Optional
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com  # Custom RPC for x402
UNBROWSE_PASSWORD=your_encryption_password  # For credential decryption
DEV_MODE=true  # Show API usage docs in search results
ENABLE_INDEX_TOOL=true  # Enable API indexing tool

Use Cases

• Investment Analysis - Aggregate financial data across platforms
• Social Media Management - Automate cross-platform posting
• Customer Support - Integrate with ticketing systems
• E-commerce - Monitor prices, manage inventory
• Project Management - Sync tasks across tools

See the documentation for detailed use cases.

Development

# Clone the repository
git clone https://github.com/getfoundry/unbrowse-mcp.git
cd unbrowse-mcp

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Links

• Documentation
• NPM Package
• Smithery
• GitHub
• Issues