browser-mcp — Turn any webpage into an MCP server

1 Install

<script src="https://cdn.jsdelivr.net/npm/@rckflr/browser-mcp@0.3.0/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.

Features

Tools

Let agents perform actions on your site

Resources

Expose data via URIs (static or template)

Prompts

Pre-built templates for agent interactions

Auth + Roles

Token-based auth with role restrictions

Session Management

Auto-expiring sessions (1h TTL)

Widget

Floating status indicator with tool list

BroadcastChannel

Cross-tab communication for agents

WordPress Plugin

13 tools for WP admin automation

API Reference

Constructor

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

Registration

`mcp.tool(name, desc, schema, handler, opts?)`	Register a tool. opts: `{ public, roles }`
`mcp.resource(uri, desc, mime?, handler)`	Expose data. URI templates: `"data://{id}"`
`mcp.prompt(name, desc, args, handler)`	Prompt template
`mcp.requireAuth(verifier)`	`(token) => user \| null`
`mcp.enableSampling(handler?)`	Enable sampling. Optional custom handler, default shows modal.
`mcp.createSamplingMessage(params)`	Request completion from user/LLM. Callable from tool handlers.

Lifecycle

`await mcp.start()`	Start server, show widget
`mcp.stop()`	Stop server, remove widget
`mcp.listTools()`	Get tool names array

Direct Access

`mcp.handleRequest(jsonRpc)`	Call MCP method directly (for testing)
`window._browserMCP`	Global reference after start()

Auth Flow (for agents)

1.	Call `auth_login` with token → get session ID
2.	Include `_auth_token` in all tool calls
3.	Sessions expire after 1 hour

Live Playground

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

Tool name

Arguments (JSON)

Click a button to see results...

WordPress Plugin

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

Tool	Roles	Action
`wp_site_info`	public	Site metadata
`wp_search`	public	Search posts/pages
`wp_list_posts`	auth	List posts
`wp_create_post`	editor+	Create post
`wp_update_post`	editor+	Edit post
`wp_delete_post`	editor+	Delete post
`wp_list_users`	admin	List users
`wp_get_settings`	admin	WP settings
`wp_list_plugins`	admin	Installed plugins

View plugin source on GitHub

Use Cases

E-commerce

Agents search products, check inventory, add to cart

CMS / WordPress

Create posts, manage content, moderate comments

Dashboards

Expose metrics and KPIs to AI analysis

Documentation

Make docs searchable and navigable by agents

Internal Tools

AI-automate any web app your team uses

Prototyping

Quickly expose any page for agent testing