Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Model Context Protocol

Expose browser tools to MCP clients and gateways.

Quickstart (stdio binary)

Install Chromium once, then point any MCP client at the package binary:
npx playwright install chromium
{
  "mcpServers": {
    "libretto-browser-tools": {
      "command": "npx",
      "args": ["-y", "libretto-browser-tools"]
    }
  }
}
Equivalent forms: npx -y libretto-browser-tools mcp, npx -y libretto-browser-tools --headed for a visible local browser, or npx -y libretto-browser-tools --provider kernel for a cloud provider.
Flags:
FlagEffect
--provider <name>Browser provider: local (default), kernel, browserbase, browser-use, steel, libretto-cloud
--headedShow the browser window (default is headless). Applies to local, kernel, and libretto-cloud
--allowed-domain <host>Restrict http(s) navigations to this host (repeatable)
--blocked-domain <host>Block http(s) navigations to this host (repeatable)
Cloud providers read API keys from the MCP server environment (for example KERNEL_API_KEY, BROWSERBASE_API_KEY, BROWSER_USE_API_KEY, STEEL_API_KEY, LIBRETTO_API_KEY). See each provider page for required variables. Local Chromium (npx playwright install chromium) is only required for --provider local.
The server exposes browser_open, browser_connect, browser_exec, browser_snapshot, browser_status, and browser_close.
Host-specific setup:

Library: registerMcpBrowserTools

Import from libretto-browser-tools/mcp when you own the MCP server and transport. Install the package (the MCP SDK is included as a dependency).
pnpm add libretto-browser-tools
npx playwright install chromium
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { LocalBrowserProvider } from "libretto-browser-tools";
import { registerMcpBrowserTools } from "libretto-browser-tools/mcp";

const server = new McpServer({
  name: "libretto-browser-tools",
  version: "1.0.0",
});
const { dispose } = registerMcpBrowserTools(
  server,
  new LocalBrowserProvider({ headless: true }),
  // optional: { allowedDomains: ["example.com"] }
);

await server.connect(new StdioServerTransport());

async function shutdown() {
  await server.close();
  await dispose();
}

process.once("SIGINT", shutdown);
process.once("SIGTERM", shutdown);
Pass domain policy options as the third argument — see Advanced. Swap LocalBrowserProvider for any provider.

Connect a gateway

MCP gateways such as Executor need a Streamable HTTP MCP URL. Mount a caller-owned server on your HTTP host, register the browser tools on it, then add that URL as an MCP integration.
Hosted gateways cannot reach a server bound to localhost. Deploy the MCP server on a reachable host, or run the gateway and server on the same network.
Create one browser toolkit per authenticated user or connection. A shared toolkit also shares its browser session registry, including sessions returned by browser_status.

Tool results

Tool failures set MCP isError: true and keep the actionable Libretto error in text content. A browser_snapshot call with screenshot: true returns the accessibility tree as text and the PNG as MCP image content.
The adapter publishes safety annotations for each tool. browser_exec is marked destructive and open-world because one Playwright script can read or change any page the browser can reach. Enforce access with host policies and domain policy; annotations are hints, not a sandbox.

See also

Powered byHolocron