Chrome Extension Bridge MCP

A Chrome extension that establishes a WebSocket connection between web pages and a local MCP server. This allows you to interact with web page resources and execute functions from your mcp server.

Inspired by playcanvas/editor-mcp-server.

Overview

This project consists of two main components:

1. Chrome Extension: Injects a client script into web pages that establishes a WebSocket connection to your local server.
2. Local MCP Server: A WebSocket server that can send commands to the extension and receive responses.

With this setup, you can:

• Access browser APIs and DOM elements from your local server
• Execute JavaScript functions in the context of web pages
• Retrieve resources and information from web pages
• Especially, access the global object like editor, e.x : https://threejs.org/editor/. You can use window.editor which is exposed by the website to control the editor. Just like playcanvas/editor-mcp-server.

Installation

Setup

1. Clone the repository:

git clone https://github.com/yourusername/chrome-extension-socket-mcp.git
cd chrome-extension-socket-mcp

2. Install dependencies:

npm install

Development

Run the following command to build the extension in development mode:

npm run debug

Loading the Extension

1. Open Chrome and navigate to chrome://extensions/
2. Enable "Developer mode" by toggling the switch in the top right corner
3. Click "Load unpacked" and select the extension folder from this project
4. The extension is now installed. You should see a small red indicator in the top right corner of any web page indicating "MCP Extension Loaded"

Usage

Server-side

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod"; 
import { Client } from "../src/client";

// Define the port for WebSocket connection
// This should match the port in your Chrome extension's WebSocket connection
const port = 54319;
const client = new Client(port);

// Establish connection to the Chrome extension
await client.connect();

// Create a new MCP server instance with name and version
const server = new McpServer({
  name: "Extension-Socket-Server",
  version: "1.0.0",
});

// Register a tool that executes the window.alert function in the browser
// This demonstrates how to interact with browser APIs from your server
server.tool(
  "alert",                  // Tool name
  "use window.alert",       // Tool description
  { message: z.string() },  // Tool parameters schema using Zod
  async ({ message }) => {  // Tool implementation function
    // Call the extension to execute alert in the browser context
    const response = await client.callToolExtension("alert", { message });
    return response;
  }
);

// Register a resource to retrieve the browser's user agent
// This demonstrates how to access browser properties from your server
server.resource(
  "userAgent",              // Resource name
  "useragent://chrome",     // Resource URI template
  async (uri) => {          // Resource handler function
    // Get the user agent from the browser
    const { content } = await client.callResourceExtension("navigator.userAgent");
    // Return the formatted resource
    return {
      contents: [
        {
          uri: uri.href,
          text: content[0].text,
        },
      ],
    };
  }
);

// Set up a transport layer for the MCP server
// StdioServerTransport uses standard input/output for communication
const transport = new StdioServerTransport();
await server.connect(transport);

// Handle application termination gracefully
process.on("SIGINT", async () => {
  console.log("SIGINT signal received");  // Log when SIGINT is received
  await client.dispose();                 // Close the WebSocket connection
  process.exit(0);                        // Exit the process
});

Extension-side

The extension automatically connects to ws://localhost:54319 by default. You can modify this in extension/content.js.

The extension exposes two main entry points for server commands:

• mcp:resource.* - For accessing browser resources and properties
• mcp:tool.* - For executing functions in the browser context

API Reference

Client

• new Client(port) - Create a new client instance connecting to specified port
• connect() - Connect to the MCP server
• callToolExtension(toolName, params) - Call a tool in the browser
• callResourceExtension(resourceName, params) - Get a resource from the browser
• dispose() - Close the connection

WebSocket Protocol

The extension uses a simple JSON-RPC-like protocol:

Request:

{
  "id": "unique-request-id",
  "method": "mcp:resource.navigator.userAgent",
  "params": {}
}

Response:

{
  "id": "unique-request-id",
  "result": "Mozilla/5.0 ..."
}

License

MIT