@browsa/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @browsa/mcp
+
+**Drive anti-detect browsers from Claude Desktop, Cursor, Cline, and any MCP-compatible client.**
+
+MCP (Model Context Protocol) server for [Browsa](https://browsa.io) — turn any LLM into a real-browser agent with one config line. The agent gets a freshly-spawned macOS-Chrome-fingerprinted Chromium with built-in CAPTCHA solving, human-shaped behavioral pacing, and a live noVNC stream so you can watch it work.
+
+[![npm version](https://img.shields.io/npm/v/@browsa/mcp.svg)](https://www.npmjs.com/package/@browsa/mcp)
+
+## What this is
+
+Most "AI agent" setups stop at the LLM. We give the LLM a real browser. Through MCP, Claude can now:
+- Navigate, fill forms, click, scroll, scrape
+- Pass through Cloudflare Turnstile, hCaptcha, reCAPTCHA, ALTCHA
+- Run from a residential US/UK/DE/etc. exit IP
+- Stay logged in across calls via persistent identities
+
+No code from you — just configure Claude Desktop (or Cursor / Cline / Zed) once, and ask in natural language.
+
+## Install
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "browsa": {
+      "command": "npx",
+      "args": ["-y", "@browsa/mcp"],
+      "env": {
+        "BROWSA_API_KEY": "agt_live_...",
+        "BROWSA_LLM_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask: *"Go to news.ycombinator.com and tell me the top story title."*
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "browsa": {
+      "command": "npx",
+      "args": ["-y", "@browsa/mcp"],
+      "env": { "BROWSA_API_KEY": "agt_live_...", "BROWSA_LLM_API_KEY": "sk-ant-..." }
+    }
+  }
+}
+```
+
+### Cline / Continue / Zed
+
+Any MCP-spec-compliant client. Point at `npx -y @browsa/mcp` and set the two env vars.
+
+## Required env
+
+| Var | Required | What |
+|---|---|---|
+| `BROWSA_API_KEY` | yes | Your `agt_live_*` key from [browsa.io → Keys](https://browsa.io/dashboard/keys) |
+| `BROWSA_LLM_API_KEY` | recommended | Default LLM provider key (e.g. Anthropic). Without this, Claude must pass it on every `run_task` call |
+| `NEOUT_LLM` | no | Default LLM. Defaults to `claude-opus-4-7` |
+| `NEOUT_COUNTRY` | no | Default egress country (e.g. `US`) |
+| `NEOUT_BASE_URL` | no | Override prod URL (staging / self-hosted) |
+
+## Tools exposed
+
+| Tool | What |
+|---|---|
+| `run_task` | Run a browser-driven task. Returns final result + live noVNC URL. |
+| `get_job` | Poll a long-running task. Optional server-side `wait_seconds`. |
+| `cancel_job` | Cancel a running task. |
+| `respond_to_job` | Answer an `input_required` prompt (CAPTCHA, decision). |
+| `credits` | Show credit balance + top-up packs. |
+| `list_webhooks` / `create_webhook` / `delete_webhook` | Webhook CRUD. |
+| `list_identities` | List persistent browser identities (use one via `profile_id` to reuse warmed cookies). |
+
+## Why MCP-first matters
+
+Most agent platforms gate distribution behind "write code → deploy → call our API." We gate it behind "paste config → ask Claude." For an AI agent platform, **the prospect's first 30 seconds is the make-or-break moment.** With this MCP server, the first 30 seconds is a working browser doing what they asked.
+
+## Source + Issues
+
+- Source: <https://github.com/mohasaaid/neout/tree/main/sdks/@browsa/mcp>
+- Issues: <https://github.com/mohasaaid/neout/issues>
+- API reference: <https://browsa.io/docs>
+
+## License
+
+MIT.

package/dist/server.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { Client, NeoutError } from "browsa";
+var API_KEY = process.env.BROWSA_API_KEY;
+var BASE_URL = process.env.NEOUT_BASE_URL;
+var DEFAULT_LLM = process.env.NEOUT_LLM ?? "claude-opus-4-7";
+var DEFAULT_LLM_KEY = process.env.BROWSA_LLM_API_KEY;
+var DEFAULT_COUNTRY = process.env.NEOUT_COUNTRY;
+if (!API_KEY) {
+  console.error("[browsa-mcp] BROWSA_API_KEY env var is required");
+  console.error("           Mint one at https://browsa.io/dashboard/keys");
+  process.exit(2);
+}
+var client = new Client({
+  apiKey: API_KEY,
+  ...BASE_URL ? { baseUrl: BASE_URL } : {}
+});
+var server = new Server(
+  { name: "browsa", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+var tools = [
+  {
+    name: "run_task",
+    description: "Run a browser-driven AI task on a fresh anti-detect Chromium burner. Returns the final result, total steps, and a live noVNC URL the user can open to watch the browser drive in real time. Use this when the user asks for anything web-shaped: scrape, fill, click, extract, login, place an order, search, summarize a page, etc. The browser is a real macOS-Chrome-fingerprinted Chromium with built-in CAPTCHA solving (Turnstile, hCaptcha, reCAPTCHA, ALTCHA, FunCaptcha) and behavioral humanization. Default timeout: 10 minutes.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: {
+          type: "string",
+          description: "Plain-English instructions for the browser agent. Be specific about what to extract and the desired output shape (JSON, list, etc.). Example: 'Go to news.ycombinator.com and return the top 3 story titles + URLs as JSON.'"
+        },
+        llm: {
+          type: "string",
+          description: `LLM identifier (default: ${DEFAULT_LLM}). Common: claude-opus-4-7, claude-sonnet-4-6, gpt-4o.`
+        },
+        llm_api_key: {
+          type: "string",
+          description: "LLM provider API key (sk-ant-... / sk-...). Required if not set via BROWSA_LLM_API_KEY env."
+        },
+        country: {
+          type: "string",
+          description: `2-letter egress country (e.g. US, GB, DE). Default: ${DEFAULT_COUNTRY ?? "auto"}.`
+        },
+        max_steps: { type: "integer", description: "Max agent steps. Default 25. Increase for complex multi-page tasks." },
+        initial_url: { type: "string", description: "Optional pre-navigation URL (saves the first agent step)." },
+        ja3_profile: {
+          type: "string",
+          description: "TLS handshake spoof profile (e.g. macos_chrome_137). Useful for TLS-fingerprinted sites."
+        },
+        profile_id: {
+          type: "string",
+          description: "Persistent identity UUID. If set, reuses an existing browser identity (cookies, history, fingerprint stay sticky). Omit for a fresh burner."
+        },
+        timeout_minutes: {
+          type: "integer",
+          description: "Max wall-clock minutes to wait before returning. Default 10.",
+          minimum: 1,
+          maximum: 30
+        }
+      }
+    }
+  },
+  {
+    name: "get_job",
+    description: "Fetch the current state of a previously-submitted job by UUID. Returns status (queued|running|completed|failed|cancelled|input_required), step count, final_result text if terminal, and the live_url for the noVNC stream. Cheap \u2014 call repeatedly to poll a long-running job started by run_task.",
+    inputSchema: {
+      type: "object",
+      required: ["job_id"],
+      properties: {
+        job_id: { type: "string", description: "Job UUID returned by run_task or list_jobs." },
+        wait_seconds: {
+          type: "integer",
+          description: "If set (1-120), block server-side until the job reaches a terminal state or N seconds elapse.",
+          minimum: 0,
+          maximum: 120
+        }
+      }
+    }
+  },
+  {
+    name: "cancel_job",
+    description: "Cancel a running job. Idempotent \u2014 returns success even if the job already terminated.",
+    inputSchema: {
+      type: "object",
+      required: ["job_id"],
+      properties: { job_id: { type: "string", description: "Job UUID." } }
+    }
+  },
+  {
+    name: "respond_to_job",
+    description: "Answer an input_required prompt (CAPTCHA solution, human decision point). Flips the job back to running.",
+    inputSchema: {
+      type: "object",
+      required: ["job_id", "response"],
+      properties: {
+        job_id: { type: "string" },
+        response: { type: "string", description: "Your answer to the agent's question." }
+      }
+    }
+  },
+  {
+    name: "credits",
+    description: "Get the current credit balance + available top-up packs.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "list_webhooks",
+    description: "List webhook subscriptions for this workspace.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "create_webhook",
+    description: "Register a callback URL the platform will POST lifecycle events to (HMAC-SHA256 signed via X-Agents-Signature). Use the verify helper from browsa/webhooks in your receiver.",
+    inputSchema: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: { type: "string", description: "HTTPS endpoint you control." },
+        events: {
+          type: "array",
+          items: { type: "string" },
+          description: "Event filter. Omit/empty for ALL events. Examples: job.completed, job.failed, agent.started."
+        }
+      }
+    }
+  },
+  {
+    name: "delete_webhook",
+    description: "Delete (disable) a webhook subscription by id.",
+    inputSchema: {
+      type: "object",
+      required: ["webhook_id"],
+      properties: { webhook_id: { type: "string" } }
+    }
+  },
+  {
+    name: "list_identities",
+    description: "List persistent browser identities (long-lived cookies/history/fingerprint, billed monthly). Use one in run_task via profile_id to reuse a warmed-up session \u2014 critical for sites that fingerprint cookie age, session continuity, or behavioral history (Akamai, Cloudflare-strict, DataDome).",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+function ok(payload) {
+  return {
+    content: [{ type: "text", text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2) }]
+  };
+}
+function fail(message, extra) {
+  const body = extra ? { error: message, ...extra } : { error: message };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(body, null, 2) }]
+  };
+}
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const name = req.params.name;
+  const args = req.params.arguments ?? {};
+  try {
+    switch (name) {
+      case "run_task": {
+        const llm = args.llm ?? DEFAULT_LLM;
+        const llmKey = args.llm_api_key ?? DEFAULT_LLM_KEY;
+        if (!llmKey) {
+          return fail(
+            "llm_api_key is required (or set BROWSA_LLM_API_KEY in the MCP env). Most users add their Anthropic key once via the env and never pass it per-call."
+          );
+        }
+        const job = await client.runTask({
+          task: args.task,
+          llm,
+          llmApiKey: llmKey,
+          country: args.country ?? DEFAULT_COUNTRY,
+          maxSteps: args.max_steps,
+          initialUrl: args.initial_url,
+          ja3Profile: args.ja3_profile,
+          profileId: args.profile_id,
+          timeoutMs: (args.timeout_minutes ?? 10) * 6e4
+        });
+        return ok({
+          job_id: job.id,
+          status: job.status,
+          steps: `${job.stepCount}/${job.progressTotal}`,
+          live_url: job.liveUrl,
+          credits_charged: job.creditsCharged,
+          final_result: job.finalResult,
+          error: job.errorMessage
+        });
+      }
+      case "get_job": {
+        const job = await client.getJob(args.job_id, { wait: args.wait_seconds ?? 0 });
+        return ok({
+          job_id: job.id,
+          status: job.status,
+          steps: `${job.stepCount}/${job.progressTotal}`,
+          live_url: job.liveUrl,
+          input_question: job.inputQuestion,
+          final_result: job.finalResult,
+          error: job.errorMessage
+        });
+      }
+      case "cancel_job": {
+        await client.cancelJob(args.job_id);
+        return ok({ cancelled: args.job_id });
+      }
+      case "respond_to_job": {
+        const job = await client.respondToJob(args.job_id, args.response);
+        return ok({ job_id: job.id, status: job.status });
+      }
+      case "credits":
+        return ok(await client.credits());
+      case "list_webhooks":
+        return ok(await client.listWebhooks());
+      case "create_webhook":
+        return ok(await client.createWebhook({ url: args.url, events: args.events }));
+      case "delete_webhook":
+        await client.deleteWebhook(args.webhook_id);
+        return ok({ deleted: args.webhook_id });
+      case "list_identities":
+        return ok(await client.listIdentities());
+      default:
+        return fail(`unknown tool: ${name}`);
+    }
+  } catch (e) {
+    if (e instanceof NeoutError) {
+      return fail(e.message, {
+        code: e.code,
+        status: e.status,
+        request_id: e.requestId
+      });
+    }
+    return fail(e.message || String(e));
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[browsa-mcp] ready (tools=" + tools.length + ")");
+}
+main().catch((e) => {
+  console.error("[browsa-mcp] fatal:", e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@browsa/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Browsa \u2014 drive anti-detect cloud browsers from Claude Desktop, Cursor, Cline, and any MCP-compatible client",
+  "license": "MIT",
+  "author": "Browsa <support@browsa.io>",
+  "homepage": "https://browsa.io",
+  "bugs": {
+    "email": "support@browsa.io"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "anthropic",
+    "browser-automation",
+    "anti-detect",
+    "ai-agents",
+    "browser-use"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "browsa-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/server.ts --format esm --target node18 --clean --shims",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "browsa": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8",
+    "typescript": "^5"
+  }
+}