browser-mcp

1 Install

<script src="https://cdn.jsdelivr.net/npm/@rckflr/[email protected]/browser-mcp.js"></script>

Or: npm install @rckflr/browser-mcp

2 Register Tools

const mcp = new BrowserMCP({ name: "My Site" });

// Public tool — anyone can call
mcp.tool("search", "Search this page", { query: "string" },
  ({ query }) => document.body.innerText.includes(query) ? "Found" : "Not found",
  { public: true }
);

// Protected tool — requires auth
mcp.tool("edit_page", "Edit page content", { html: "string" },
  ({ html }, user) => { document.body.innerHTML = html; return "Updated by " + user.name; },
  { roles: ["admin"] }
);

3 Add Auth (Optional)

// Simple token-based auth
const TOKENS = {
  "secret-admin-key": { id: "admin", role: "admin", name: "Admin" },
  "editor-key":       { id: "editor", role: "editor", name: "Editor" },
};
mcp.requireAuth((token) => TOKENS[token] || null);

// Or verify against your API
mcp.requireAuth(async (token) => {
  const res = await fetch("/api/verify", { headers: { Authorization: `Bearer ${token}` } });
  return res.ok ? await res.json() : null;
});

4 Start

mcp.start();
// Widget appears. Agents can connect. That's it.

5 mcpTool() — Universal API

Works in both standalone mode (browser-mcp.js) and MCP Browser (Tauri desktop app).

// Register a tool that works in BOTH runtimes
mcpTool("search", "Search products",
  { query: { type: "string" } },
  (args) => products.filter(p => p.name.includes(args.query))
);

In standalone mode, tools sync with BrowserMCP on start(). In MCP Browser, the bridge picks them up automatically. See shop demo →

MCP Browser — Desktop App

A custom Tauri browser with a built-in MCP HTTP server. Any page you visit exposes tools to external AI agents via POST http://localhost:PORT/mcp.

⬇ Download (Windows, macOS, Linux)  |  GitHub →

Connect Your Agent

Two ways to connect an AI agent to a site running browser-mcp:

Option A — MCP Browser (recommended)

Download MCP Browser, open any site, and point your agent to the HTTP server:

# 1. Download and launch MCP Browser
# 2. Navigate to any site (e.g. browser-mcp.automators.work/mcp-shop-demo.html)
# 3. Connect your agent:

# Claude Code
claude mcp add mcp-browser --transport http --url http://127.0.0.1:4567/mcp

# Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "mcp-browser": {
      "url": "http://127.0.0.1:4567/mcp"
    }
  }
}

# Any agent — just POST
curl -X POST http://127.0.0.1:4567/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Option B — BroadcastChannel (same browser)

For agents running in the same browser, connect via BroadcastChannel:

const channel = new BroadcastChannel("browser-mcp");
channel.postMessage({
  jsonrpc: "2.0", id: 1,
  method: "tools/list", params: {}
});
channel.onmessage = (e) => console.log(e.data);

Features

Prompts

Prompts are pre-built templates that agents can discover and use to structure their interactions with your site. Define them once, and any connected agent can list and invoke them.

// Summarize page content with a focus area
mcp.prompt("summarize", "Summarize this page",
  [{ name: "focus", description: "What to focus on" }],
  ({ focus }) => `Summarize this page, focusing on ${focus}. Content: ${document.body.innerText.slice(0, 3000)}`
);

// Generate a code review prompt
mcp.prompt("code_review", "Review code on this page",
  [{ name: "language", description: "Programming language" }],
  ({ language }) => `Review the ${language} code on this page for bugs, security issues, and improvements.`
);

// Translate page content
mcp.prompt("translate", "Translate page content",
  [{ name: "target_lang", description: "Target language" }],
  ({ target_lang }) => `Translate the following to ${target_lang}: ${document.body.innerText.slice(0, 2000)}`
);

Agents discover prompts via prompts/list and invoke them with prompts/get. Arguments are passed as key-value pairs.

Resources

Resources expose data from your site via URIs that agents can read. They can be static (fixed URI) or dynamic (URI templates with parameters).

// Static resource — fixed URI
mcp.resource("page://title", "Page title", "text/plain",
  () => document.title
);

mcp.resource("page://content", "Full page text", "text/plain",
  () => document.body.innerText.slice(0, 5000)
);

// Dynamic resource — URI template with parameter
mcp.resource("page://meta/{name}", "Get meta tag value", "text/plain",
  ({ name }) => {
    const meta = document.querySelector(`meta[name="${name}"]`);
    return meta ? meta.content : "Not found";
  }
);

// JSON resource
mcp.resource("page://links", "All links on this page", "application/json",
  () => JSON.stringify([...document.querySelectorAll('a[href]')].map(a => ({
    text: a.textContent.trim(), href: a.href
  })))
);

Agents discover resources via resources/list and read them with resources/read. URI templates (with {param}) appear in resources/templates/list.

Sampling

Sampling lets your tools request LLM completions through the connected agent. The user sees a modal to approve or edit the response (human-in-the-loop).

// Enable sampling (shows approval modal by default)
mcp.enableSampling();

// Use sampling inside a tool handler
mcp.tool("ask_ai", "Ask AI a question about this page",
  { question: "string" },
  async ({ question }) => {
    const result = await mcp.createSamplingMessage({
      messages: [{
        role: "user",
        content: { type: "text", text: question }
      }],
      systemPrompt: "You are a helpful assistant. Use the page context to answer.",
      maxTokens: 200
    });
    return result.content.text;
  },
  { public: true }
);

You can also provide a custom handler to enableSampling(fn) to skip the modal and handle sampling programmatically.

API Reference

Constructor

new BrowserMCP({ name, version, description, widget, endpoint })

Registration

Lifecycle

Direct Access

Auth Flow (for agents)

Live Playground

This page is running a BrowserMCP server right now. Try calling tools:

WordPress Plugin

Drop the plugin into wp-content/plugins/browser-mcp/ and activate. 13 tools auto-registered:

View plugin source on GitHub

Use Cases