extension-tools

@mcp-b/extension-tools

62+ Chrome Extension API tools for Model Context Protocol - Let Claude, ChatGPT, and Gemini control your browser

Full Documentation | Quick Start

@mcp-b/extension-tools exposes Chrome Extension APIs as MCP tools, enabling AI agents like Claude, ChatGPT, Gemini, Cursor, and Copilot to control browser tabs, manage bookmarks, access history, execute scripts, and more.

Why Use @mcp-b/extension-tools?

Feature	Benefit
62+ Chrome APIs	Comprehensive coverage of Chrome Extension APIs
AI-Ready	Built for MCP, the standard for AI tool integration
Granular Control	Enable only the APIs your extension needs
Permission Aware	Automatic permission checking and clear error messages
Manifest V3	Full support for Chrome's latest extension platform
TypeScript	Complete type definitions for all 62+ APIs

Use Cases

• AI Browser Assistants: Let AI agents manage tabs, bookmarks, and browsing history
• Automated Testing: AI-driven browser automation and testing
• Research Tools: AI can search history, manage reading lists, and organize bookmarks
• Productivity Extensions: AI helps with tab management, session saving, and workflow automation
• Enterprise Tools: AI-powered browser management and policy enforcement

Overview

This package provides a comprehensive set of tool classes that expose Chrome Extension APIs through the Model Context Protocol (MCP). Each API is wrapped in a dedicated class that handles permission checking, error handling, and tool registration.

Currently, 62 out of 74 Chrome Extension APIs have been implemented and are ready to use. See the API Implementation Status section below for a complete list of available and pending APIs.

Installation

npm install @mcp-b/extension-tools @modelcontextprotocol/sdk
# or
pnpm add @mcp-b/extension-tools @modelcontextprotocol/sdk
# or
yarn add @mcp-b/extension-tools @modelcontextprotocol/sdk

API Implementation Status

Available API Tools (62 APIs)

The following Chrome Extension APIs have been fully implemented and are ready to use:

• AlarmsApiTools - Set and manage alarms
• AudioApiTools - Audio device management
• BookmarksApiTools - Manage browser bookmarks
• BrowsingDataApiTools - Clear browsing data
• CertificateProviderApiTools - Provide certificates for TLS authentication
• CommandsApiTools - Manage keyboard shortcuts
• ContentSettingsApiTools - Manage content settings
• ContextMenusApiTools - Create context menu items
• CookiesApiTools - Manage browser cookies
• DebuggerApiTools - Debug network and JavaScript
• DeclarativeContentApiTools - Take actions based on content
• DeclarativeNetRequestApiTools - Modify network requests
• DesktopCaptureApiTools - Capture desktop content
• DevtoolsInspectedWindowApiTools - Interact with inspected window
• DevtoolsNetworkApiTools - Retrieve network information
• DevtoolsPanelsApiTools - Create DevTools panels
• DocumentScanApiTools - Scan documents
• DomApiTools - Access DOM from extensions
• DownloadsApiTools - Control file downloads
• EnterpriseDeviceAttributesApiTools - Access enterprise device attributes
• EnterpriseHardwarePlatformApiTools - Access enterprise hardware info
• EnterpriseNetworkingAttributesApiTools - Access enterprise network attributes
• EnterprisePlatformKeysApiTools - Enterprise platform keys
• ExtensionApiTools - Extension utilities
• FileBrowserHandlerApiTools - Handle file browser events
• FileSystemProviderApiTools - Provide file systems
• FontSettingsApiTools - Manage font settings
• GcmApiTools - Google Cloud Messaging
• HistoryApiTools - Search and manage browsing history
• I18nApiTools - Internationalization utilities
• IdentityApiTools - OAuth2 authentication
• IdleApiTools - Detect idle state
• InputImeApiTools - Input method editor
• InstanceIDApiTools - Instance ID operations
• LoginStateApiTools - Read login state
• ManagementApiTools - Manage extensions
• NotificationsApiTools - Create system notifications
• OffscreenApiTools - Manage offscreen documents
• OmniboxApiTools - Customize address bar
• PageCaptureApiTools - Save pages as MHTML
• PermissionsApiTools - Request optional permissions
• PlatformKeysApiTools - Platform-specific keys
• PowerApiTools - Power management
• PrintingApiTools - Print documents
• PrintingMetricsApiTools - Printing metrics
• ProxyApiTools - Manage proxy settings
• ReadingListApiTools - Access reading list
• RuntimeApiTools - Access extension runtime information
• ScriptingApiTools - Execute scripts and inject CSS
• SearchApiTools - Search via default provider
• SessionsApiTools - Query and restore browser sessions
• SidePanelApiTools - Control side panel
• StorageApiTools - Access extension storage (local, sync, session)
• SystemCpuApiTools - Query CPU information
• SystemLogApiTools - Add system log entries
• SystemMemoryApiTools - Get memory information
• SystemStorageApiTools - Query storage devices
• TabCaptureApiTools - Capture tab media streams
• TabGroupsApiTools - Manage tab groups
• TabsApiTools - Create, update, query, and manage browser tabs
• TopSitesApiTools - Access top sites
• TtsApiTools - Text-to-speech functionality
• TtsEngineApiTools - Implement TTS engine
• UserScriptsApiTools - Execute user scripts
• VpnProviderApiTools - Implement VPN client
• WallpaperApiTools - Set wallpaper
• WebAuthenticationProxyApiTools - Web authentication proxy
• WebNavigationApiTools - Monitor web navigation
• WebRequestApiTools - Intercept and modify requests
• WindowsApiTools - Control browser windows

APIs Under Development (12 APIs)

The following Chrome Extension APIs are not yet implemented or need additional work:

• AccessibilityFeaturesApiTools - Manage accessibility features
• ActionApiTools - Control extension's action button
• DevtoolsPerformanceApiTools - Access performance data
• DevtoolsRecorderApiTools - DevTools recorder panel
• DnsApiTools - DNS resolution
• EventsApiTools - Common event handling
• ExtensionTypesApiTools - Extension type definitions
• PrinterProviderApiTools - Provide printers
• PrivacyApiTools - Control privacy features
• ProcessesApiTools - Interact with browser processes
• SystemDisplayApiTools - Query display information
• TypesApiTools - Chrome type definitions

Usage

Server Setup

Create an MCP server in your Chrome extension's background script:

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

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

// Register individual API tools with specific methods enabled
const tabsTools = new TabsApiTools(server, {
  listActiveTabs: true,
  createTab: true,
  updateTab: true,
  closeTabs: true,
  getAllTabs: true,
  navigateHistory: true,
  reloadTab: true,
});
tabsTools.register();

const bookmarksTools = new BookmarksApiTools(server, {
  getBookmarks: true,
  createBookmark: true,
  updateBookmark: true,
  removeBookmark: true,
});
bookmarksTools.register();

const storageTools = new StorageApiTools(server, {
  getStorage: true,
  setStorage: true,
  removeStorage: true,
  clearStorage: true,
});
storageTools.register();

// Connect to transport
const transport = new WebsocketServerTransport({
  port: 3000,
});
await server.connect(transport);

Client Usage

Connect to the server and call the registered tools:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { WebsocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';

// Create and connect client
const client = new Client({
  name: 'my-mcp-client',
  version: '1.0.0',
});

const transport = new WebsocketClientTransport(new URL('ws://localhost:3000'));
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Call extension tools
// Create a new tab
const createResult = await client.callTool({
  name: 'create_tab',
  arguments: {
    url: 'https://example.com',
    active: true,
    pinned: false,
  },
});

// Get all tabs
const tabsResult = await client.callTool({
  name: 'get_all_tabs',
  arguments: {
    currentWindow: true,
  },
});

// Search bookmarks
const bookmarksResult = await client.callTool({
  name: 'get_bookmarks',
  arguments: {
    query: 'example',
  },
});

// Store data
const storageResult = await client.callTool({
  name: 'set_storage',
  arguments: {
    area: 'local',
    items: {
      key1: 'value1',
      key2: { nested: 'object' },
    },
  },
});

// Execute script in active tab
const scriptResult = await client.callTool({
  name: 'execute_script',
  arguments: {
    target: { tabId: undefined }, // defaults to active tab
    func: '() => document.title',
  },
});

Tool Configuration

Each API tool class accepts configuration options to enable specific methods:

// TabsApiTools options
interface TabsOptions {
  listActiveTabs?: boolean;
  createTab?: boolean;
  updateTab?: boolean;
  closeTabs?: boolean;
  getAllTabs?: boolean;
  navigateHistory?: boolean;
  reloadTab?: boolean;
  captureVisibleTab?: boolean;
  detectLanguage?: boolean;
  discardTab?: boolean;
  duplicateTab?: boolean;
  getTab?: boolean;
  getZoom?: boolean;
  setZoom?: boolean;
  groupTabs?: boolean;
  ungroupTabs?: boolean;
  highlightTabs?: boolean;
  moveTabs?: boolean;
  sendMessage?: boolean;
}

// Similar options exist for other API tools

Permission Requirements

Each Chrome API requires specific permissions in your extension's manifest.json. Here are some common permissions:

{
  "manifest_version": 3,
  "permissions": [
    "activeTab",
    "alarms",
    "audio",
    "bookmarks",
    "browsingData",
    "certificateProvider",
    "contentSettings",
    "contextMenus",
    "cookies",
    "debugger",
    "declarativeContent",
    "declarativeNetRequest",
    "desktopCapture",
    "downloads",
    "fontSettings",
    "gcm",
    "history",
    "identity",
    "idle",
    "management",
    "notifications",
    "offscreen",
    "pageCapture",
    "permissions",
    "platformKeys",
    "power",
    "printing",
    "printingMetrics",
    "proxy",
    "readingList",
    "scripting",
    "search",
    "sessions",
    "sidePanel",
    "storage",
    "system.cpu",
    "system.memory",
    "system.storage",
    "tabCapture",
    "tabGroups",
    "tabs",
    "topSites",
    "tts",
    "ttsEngine",
    "unlimitedStorage",
    "vpnProvider",
    "wallpaper",
    "webAuthenticationProxy",
    "webNavigation",
    "webRequest"
  ],
  "host_permissions": [
    "<all_urls>" // Required for scripting API and some other APIs
  ],
  "optional_permissions": [
    // Add any permissions you want to request at runtime
  ]
}

Note: Not all APIs require permissions. Some APIs like i18n, runtime, and extension are available without explicit permissions. Enterprise APIs require the extension to be force-installed via enterprise policy.

Tool Examples

Tab Management

// List tabs grouped by domain
const result = await client.callTool({
  name: 'list_active_tabs',
  arguments: {},
});

// Update the active tab's URL
const updateResult = await client.callTool({
  name: 'update_tab',
  arguments: {
    url: 'https://new-url.com',
    active: true,
  },
});

// Group multiple tabs
const groupResult = await client.callTool({
  name: 'group_tabs',
  arguments: {
    tabIds: [1, 2, 3],
  },
});

Storage Operations

// Get storage data
const data = await client.callTool({
  name: 'get_storage',
  arguments: {
    area: 'local',
    keys: ['setting1', 'setting2'],
  },
});

// Clear all storage
const clearResult = await client.callTool({
  name: 'clear_storage',
  arguments: {
    area: 'local',
  },
});

History Search

// Search browsing history
const historyResult = await client.callTool({
  name: 'search_history',
  arguments: {
    text: 'github',
    maxResults: 20,
    startTime: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last week
  },
});

Architecture

Each API tool class extends BaseApiTools which provides:

• Automatic permission checking - Verifies API availability before registering tools
• Consistent error handling - Standardized error responses
• Tool registration helpers - Simplified tool registration process
• Response formatting - Consistent response format across all tools

export abstract class BaseApiTools {
  protected abstract apiName: string;

  abstract checkAvailability(): ApiAvailability;
  abstract registerTools(): void;

  register(): void {
    const availability = this.checkAvailability();
    if (availability.available) {
      console.log(`Registering ${this.apiName} API tools...`);
      this.registerTools();
    } else {
      console.warn(`${this.apiName} API not available:`, availability.message);
    }
  }
}

Error Handling

All tools include comprehensive error handling and return structured error responses:

try {
  const result = await client.callTool({
    name: 'create_tab',
    arguments: { url: 'invalid-url' },
  });
} catch (error) {
  // Error response will include:
  // - error: true
  // - content: [{ type: 'text', text: 'Error message' }]
}

Complete Example

Here's a complete example of setting up a Chrome extension with MCP tools:

// background.js - Extension background script
import {
  BookmarksApiTools,
  HistoryApiTools,
  ScriptingApiTools,
  StorageApiTools,
  TabsApiTools,
} from '@mcp-b/extension-tools';
import { ExtensionServerTransport } from '@mcp-b/transports';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

async function setupMcpServer() {
  const server = new McpServer({
    name: 'my-chrome-extension',
    version: '1.0.0',
  });

  // Register multiple API tools
  const apis = [
    new TabsApiTools(server, {
      listActiveTabs: true,
      createTab: true,
      updateTab: true,
      closeTabs: true,
      getAllTabs: true,
    }),
    new BookmarksApiTools(server, {
      getBookmarks: true,
      createBookmark: true,
    }),
    new StorageApiTools(server, {
      getStorage: true,
      setStorage: true,
    }),
    new HistoryApiTools(server, {
      searchHistory: true,
    }),
    new ScriptingApiTools(server, {
      executeScript: true,
      insertCSS: true,
    }),
  ];

  // Register all tools
  apis.forEach((api) => api.register());

  // Connect transport
  const transport = new ExtensionServerTransport();
  await server.connect(transport);

  console.log('MCP server ready with Chrome extension tools');
}

setupMcpServer();

TypeScript Support

This package is written in TypeScript and includes full type definitions for all APIs and tool parameters.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Frequently Asked Questions

Which AI agents can use these tools?

Any MCP-compatible client, including:

• Claude Desktop and Claude.ai
• Cursor IDE
• VS Code Copilot
• Gemini applications
• Windsurf, Cline, and other MCP clients

Do I need to enable all 62 APIs?

No! Each API tool class accepts configuration options. Enable only what you need:

new TabsApiTools(server, {
  listActiveTabs: true, // Only enable tab listing
  createTab: false, // Disable tab creation
});

Is Manifest V3 supported?

Yes! All tools are compatible with Chrome's Manifest V3 extension platform.

How do AI agents connect to my extension?

Use @mcp-b/transports for in-browser communication, or expose a WebSocket server for desktop AI agents.

What about Firefox and Edge?

The APIs target Chrome, but many also work in Firefox (via WebExtensions) and Edge (Chromium-based). Check browser compatibility for specific APIs.

Comparison with Alternatives

Feature	@mcp-b/extension-tools	Raw Chrome APIs	Puppeteer
MCP Protocol Support	Yes	No	No
Type Safety	Full TypeScript	Partial	Full
Permission Handling	Automatic	Manual	N/A
Error Formatting	Structured	Raw	Varies
AI Agent Ready	Yes	Manual	Manual

Related Packages

• @mcp-b/transports - Browser-specific MCP transports
• @mcp-b/global - W3C Web Model Context API polyfill
• @mcp-b/chrome-devtools-mcp - Connect desktop AI agents to browser
• @modelcontextprotocol/sdk - Official MCP SDK

Resources

• WebMCP Documentation
• Model Context Protocol Spec
• Chrome Extension APIs
• MCP GitHub Repository

License

MIT - see LICENSE for details

Support

• GitHub Issues
• Documentation
• Discord Community