WebMCP Documentation

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

Here’s an example of connecting to an MCP extension:

// 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:

Advanced Patterns - Extension development patterns
Troubleshooting - Extension-specific issues
Glossary - Extension terminology

External Resources

@modelcontextprotocol/sdk - Core MCP SDK
Chrome Extension API Reference - Official Chrome docs
MCP Protocol Specification - Protocol details
GitHub Repository - Source code

​Overview

​Prerequisites

​Installation

​Key Features

​Architecture

​Basic Usage

​Setting Up in Background Script

​Client-Side Usage

​Available API Wrappers

​Core Browser APIs

​TabsApiTools

​WindowsApiTools

​StorageApiTools

​Content & Scripting APIs

​ScriptingApiTools

​Data Management APIs

​BookmarksApiTools

​HistoryApiTools

​DownloadsApiTools

​System APIs

​SystemApiTools

​Real-World Example: Extension Connector

​Tool Registration Options

​Input Validation

​Error Handling

​Security Considerations

​Manifest Permissions

​Tool Access Control

​Complete API List

​TypeScript Support

​Related Documentation

@mcp-b/transports

Extension Guide

Core Concepts

Security Guide

​External Resources

Overview

Prerequisites

Installation

Key Features

Architecture

Basic Usage

Setting Up in Background Script

Client-Side Usage

Available API Wrappers

Core Browser APIs

TabsApiTools

WindowsApiTools

StorageApiTools

Content & Scripting APIs

ScriptingApiTools

Data Management APIs

BookmarksApiTools

HistoryApiTools

DownloadsApiTools

System APIs

SystemApiTools

Real-World Example: Extension Connector

Tool Registration Options

Input Validation

Error Handling

Security Considerations

Manifest Permissions

Tool Access Control

Complete API List

TypeScript Support

Related Documentation

External Resources