FSB MCP Server

0.7.3 verified Sat Apr 25 auth: no javascript

FSB MCP Server (v0.7.3) is a Node.js server that bridges the Model Context Protocol (MCP) to the FSB Chrome Extension, enabling AI agents (Claude, Cursor, Windsurf, etc.) to control a browser across four modes: manual, visual session, autopilot, and agent. Released under MIT license with active development (multiple releases per month), it offers 62+ tools for fine-grained browser automation, self-documenting tool descriptions, cookie consent auto-dismiss, site-aware search, and vault tools for secure credential access. Unlike Puppeteer-based solutions, it uses a Chrome extension for direct interaction with the user's existing browser session, preserving login state and avoiding remote debugging protocol complexities.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/fsb-mcp-server/dist/index.js from /path/to/your-project/app.js not supported. Instead change the require of index.js in /path/to/your-project/app.js to a dynamic import() which is available in all CommonJS modules. ↓

cause Attempting to require() an ESM-only package from a CommonJS module.

fix

Use dynamic import: const { createServer } = await import('fsb-mcp-server'); or switch your project to ESM by adding "type": "module" to package.json.

error TypeError: server.start is not a function ↓

cause Using the deprecated FSBServer constructor which no longer returns an object with .start() method, or calling .start() before the server is fully initialized.

fix

Use createServer() and await the promise: const server = await createServer(opts); server.start();

error Error: Extension not connected. Please ensure the FSB Chrome Extension is installed and the browser is running. ↓

cause The MCP server started but cannot communicate with the FSB browser extension.

fix

Install the FSB Chrome Extension from the GitHub repository, launch Chrome, and ensure the extension is active (check by navigating to chrome://extensions and verifying it is enabled).

Warnings

breaking Breaking change: v0.3.0 switched from CommonJS to ESM-only exports. Requires Node >= 18 and "type": "module" in package.json, or use dynamic import(). ↓

fix Update consuming projects to use ESM: add "type": "module" to package.json, or use import() instead of require().

breaking Breaking change: v0.3.0 renamed the main export from McpServer to FSBServer; createServer() was introduced in v0.4.0 as the recommended way to instantiate. ↓

fix Use createServer() instead of new FSBServer(). FSBServer constructor is deprecated and may be removed.

deprecated FSBServer constructor is deprecated since v0.4.0. Use createServer() factory function instead. ↓

fix Replace `new FSBServer(opts)` with `createServer(opts)`.

gotcha The default transport is stdio; to use HTTP/Streamable HTTP, you must explicitly set transport to 'http'. The httpPort option is ignored in stdio mode. ↓

fix Pass `transport: 'http'` and `httpPort: 7226` to createServer for HTTP mode.

gotcha If the FSB Chrome Extension is not installed or not connected, the server will start but all browser automation tools will fail with errors like 'Extension not connected'. The server does not auto-launch Chrome. ↓

fix Ensure the FSB Chrome Extension is installed and the browser is running before starting the MCP client.

Install

npm install fsb-mcp-server

yarn add fsb-mcp-server

pnpm add fsb-mcp-server

Imports

FSBServer
wrong
```
const FSBServer = require('fsb-mcp-server')
```
correct
```
import { FSBServer } from 'fsb-mcp-server'
```
Package is ESM-only since v0.3.0. CommonJS require() will fail with ERR_REQUIRE_ESM.
createServer
wrong
```
import createServer from 'fsb-mcp-server'
```
correct
```
import { createServer } from 'fsb-mcp-server'
```
createServer is a named export, not default. Default export is undefined.
FSBConfig
wrong
```
import { FSBConfig } from 'fsb-mcp-server'
```
correct
```
import type { FSBConfig } from 'fsb-mcp-server'
```
FSBConfig is a TypeScript type-only export. Use import type to avoid runtime errors.

Quickstart

Creates and starts an MCP server connected to the FSB Chrome Extension via stdio or HTTP transport.

import { createServer } from 'fsb-mcp-server';

const server = createServer({
  transport: 'stdio',
  port: 7225,
  httpPort: 7226,
  extensionUrl: 'ws://localhost:7225',
});

await server.start();
console.log('FSB MCP Server running on stdio');

// Or with Streamable HTTP:
// const httpServer = createServer({ transport: 'http', httpPort: 7226 });
// await httpServer.start();
// console.log('HTTP MCP endpoint at http://127.0.0.1:7226/mcp');