Skip to main content
This is a Developer Resource for building Chrome extensions with WebMCP. If you’re looking to use the MCP-B Extension, see the Extension Overview.

​
Overview

The @mcp-b/extension-tools package provides Model Context Protocol (MCP) wrappers for Chrome Extension APIs. It enables standardized, protocol-based access to browser extension functionalities, allowing MCP clients to interact with Chrome’s extensive API surface.

​
Prerequisites

  • Chrome Extension with Manifest V3
  • @mcp-b/transports package installed
  • @modelcontextprotocol/sdk installed
  • Required Chrome permissions in manifest.json
  • TypeScript 5.0+ (recommended)
  • Understanding of Chrome Extension APIs and MCP protocol

​
Installation

npm install @mcp-b/extension-tools

​
Key Features

  • MCP wrappers for 62+ Chrome Extension APIs
  • Full TypeScript support with comprehensive type definitions
  • Zod-based input validation and schema generation
  • Structured error handling and response formatting
  • Compatible with Manifest V3 extensions

​
Architecture

The package wraps Chrome Extension APIs into MCP-compatible tools, enabling remote procedure calls through the MCP protocol. Each Chrome API is wrapped in its own tools class that extends BaseApiTools.

​
Basic Usage

​
Setting Up in Background Script

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { TabServerTransport } from '@mcp-b/transports';
import { 
  TabsApiTools,
  StorageApiTools,
  BookmarksApiTools 
} from '@mcp-b/extension-tools';

// Create MCP server
const server = new McpServer({
  name: 'chrome-extension-server',
  version: '1.0.0'
});

// Register Chrome API tools
const tabsTools = new TabsApiTools(server, {
  createTab: true,
  updateTab: true,
  removeTabs: true,
  queryTabs: true
});
tabsTools.register();

const storageTools = new StorageApiTools(server, {
  getStorageData: true,
  setStorageData: true,
  removeStorageData: true
});
storageTools.register();

// Set up transport
const transport = new TabServerTransport({
  allowedOrigins: ['*']
});

// Connect server to transport
await server.connect(transport);

​
Client-Side Usage

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { TabClientTransport } from '@mcp-b/transports';

const transport = new TabClientTransport({
  targetOrigin: window.location.origin
});

const client = new Client({
  name: 'web-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Call Chrome API through MCP
const tabs = await client.callTool({
  name: 'query_tabs',
  arguments: {
    active: true,
    currentWindow: true
  }
});

const newTab = await client.callTool({
  name: 'create_tab',
  arguments: {
    url: 'https://example.com',
    active: true
  }
});

​
Available API Wrappers

​
Core Browser APIs

​
TabsApiTools

const tabsTools = new TabsApiTools(server, {
  createTab: true,        // chrome.tabs.create
  updateTab: true,        // chrome.tabs.update
  removeTabs: true,       // chrome.tabs.remove
  queryTabs: true,        // chrome.tabs.query
  getTab: true,           // chrome.tabs.get
  duplicateTab: true,     // chrome.tabs.duplicate
  highlightTabs: true,    // chrome.tabs.highlight
  moveTabs: true          // chrome.tabs.move
});

​
WindowsApiTools

const windowsTools = new WindowsApiTools(server, {
  createWindow: true,     // chrome.windows.create
  updateWindow: true,     // chrome.windows.update
  removeWindow: true,     // chrome.windows.remove
  getWindow: true,        // chrome.windows.get
  getAllWindows: true,    // chrome.windows.getAll
  getCurrentWindow: true  // chrome.windows.getCurrent
});

​
StorageApiTools

const storageTools = new StorageApiTools(server, {
  getStorageData: true,    // chrome.storage.local.get
  setStorageData: true,    // chrome.storage.local.set
  removeStorageData: true, // chrome.storage.local.remove
  clearStorage: true,      // chrome.storage.local.clear
  getBytesInUse: true      // chrome.storage.local.getBytesInUse
});

​
Content & Scripting APIs

​
ScriptingApiTools

const scriptingTools = new ScriptingApiTools(server, {
  executeScript: true,     // chrome.scripting.executeScript
  insertCSS: true,         // chrome.scripting.insertCSS
  removeCSS: true,         // chrome.scripting.removeCSS
  registerContentScripts: true,
  unregisterContentScripts: true
});

​
Data Management APIs

​
BookmarksApiTools

const bookmarksTools = new BookmarksApiTools(server, {
  createBookmark: true,    // chrome.bookmarks.create
  removeBookmark: true,    // chrome.bookmarks.remove
  updateBookmark: true,    // chrome.bookmarks.update
  searchBookmarks: true,   // chrome.bookmarks.search
  getBookmarkTree: true    // chrome.bookmarks.getTree
});

​
HistoryApiTools

const historyTools = new HistoryApiTools(server, {
  searchHistory: true,     // chrome.history.search
  addUrl: true,            // chrome.history.addUrl
  deleteUrl: true,         // chrome.history.deleteUrl
  deleteRange: true,       // chrome.history.deleteRange
  deleteAll: true          // chrome.history.deleteAll
});

​
DownloadsApiTools

const downloadsTools = new DownloadsApiTools(server, {
  download: true,          // chrome.downloads.download
  pauseDownload: true,     // chrome.downloads.pause
  resumeDownload: true,    // chrome.downloads.resume
  cancelDownload: true,    // chrome.downloads.cancel
  searchDownloads: true    // chrome.downloads.search
});

​
System APIs

​
SystemApiTools

// CPU information
const cpuTools = new SystemCpuApiTools(server, {
  getCpuInfo: true         // chrome.system.cpu.getInfo
});

// Memory information
const memoryTools = new SystemMemoryApiTools(server, {
  getMemoryInfo: true      // chrome.system.memory.getInfo
});

// Display information
const displayTools = new SystemDisplayApiTools(server, {
  getDisplayInfo: true,    // chrome.system.display.getInfo
  getDisplayLayout: true   // chrome.system.display.getDisplayLayout
});

​
Real-World Example: Extension Connector

From the extension-connector example: 
// background.ts
import { ExtensionClientTransport } from '@mcp-b/transports';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const TARGET_EXTENSION_ID = 'your-mcp-extension-id';
const PORT_NAME = 'mcp';

async function connectToMcpExtension() {
  const transport = new ExtensionClientTransport({
    extensionId: TARGET_EXTENSION_ID,
    portName: PORT_NAME,
  });
  
  const client = new Client({
    name: 'extension-client',
    version: '1.0.0'
  }, {
    capabilities: {}
  });
  
  await client.connect(transport);
  
  // Now you can call tools exposed by the MCP extension
  const tools = await client.listTools();
  console.log('Available tools:', tools);
  
  // Call a specific tool
  const tabs = await client.callTool({
    name: 'query_tabs',
    arguments: { active: true }
  });
  
  return { client, tools, tabs };
}

​
Tool Registration Options

Each API tools class accepts configuration options to control which tools are registered: 
interface TabsApiToolsOptions {
  createTab?: boolean;
  updateTab?: boolean;
  removeTabs?: boolean;
  queryTabs?: boolean;
  getTab?: boolean;
  duplicateTab?: boolean;
  highlightTabs?: boolean;
  moveTabs?: boolean;
  reloadTab?: boolean;
  captureVisibleTab?: boolean;
  executeScript?: boolean;
  insertCSS?: boolean;
  removeCSS?: boolean;
  detectLanguage?: boolean;
  setZoom?: boolean;
  getZoom?: boolean;
  setZoomSettings?: boolean;
  getZoomSettings?: boolean;
}

​
Input Validation

All tools use Zod schemas for input validation: 
// Example: TabsApiTools validation schema
const createTabSchema = z.object({
  windowId: z.number().optional(),
  index: z.number().optional(),
  url: z.string().optional(),
  active: z.boolean().optional(),
  pinned: z.boolean().optional(),
  openerTabId: z.number().optional()
});

// The tool automatically validates inputs before execution

​
Error Handling

The package provides structured error responses: 
try {
  const result = await client.callTool({
    name: 'create_tab',
    arguments: { url: 'invalid-url' }
  });
} catch (error) {
  // Error includes structured information
  console.error({
    tool: error.tool,
    message: error.message,
    validationErrors: error.validationErrors
  });
}

​
Security Considerations

​
Manifest Permissions

Ensure your extension manifest includes required permissions: 
{
  "manifest_version": 3,
  "permissions": [
    "tabs",
    "storage",
    "bookmarks",
    "history",
    "downloads"
  ],
  "host_permissions": [
    "<all_urls>"
  ],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}

​
Tool Access Control

Control which tools are exposed: 
// Only register specific tools based on permissions
chrome.permissions.contains({
  permissions: ['tabs']
}, (hasPermission) => {
  if (hasPermission) {
    const tabsTools = new TabsApiTools(server, {
      queryTabs: true,  // Read-only operations
      createTab: false, // Disable creation
      removeTabs: false // Disable deletion
    });
    tabsTools.register();
  }
});

​
Complete API List

The package provides wrappers for 62+ Chrome APIs including:
  • Browser Control: tabs, windows, browserAction, pageAction
  • Storage: storage, cookies, sessions
  • Content: bookmarks, history, downloads, topSites
  • Communication: runtime, messaging, notifications
  • DevTools: debugger, devtools
  • System: system.cpu, system.memory, system.storage, system.display
  • Identity: identity, oauth2
  • Enterprise: enterprise.platformKeys, enterprise.deviceAttributes
  • Privacy: privacy, contentSettings
  • Network: proxy, vpnProvider, webRequest
  • Management: management, permissions, commands

​
TypeScript Support

Full TypeScript definitions are provided: 
import type { 
  TabsApiToolsOptions,
  StorageApiToolsOptions,
  BookmarksApiToolsOptions 
} from '@mcp-b/extension-tools';

// Type-safe tool configuration
const options: TabsApiToolsOptions = {
  createTab: true,
  updateTab: true,
  removeTabs: false // Explicitly disable dangerous operations
};

@mcp-b/transports

Extension transport layer

Extension Guide

MCP-B browser extension

Core Concepts

Extension architecture

Security Guide

Extension security best practices
See also:

​
External Resources