Important

🚨 Important Update: Please download version 1.0.0 from NPM as this is a breaking change! 🚨

WebMCP:

🚀 Quick Start • ✨ Live Demo • 📚 Documentation • 🤝 Contributing

Join Our Community

The protocol

WebMCP is the underlying protocol which MCP-B implements. It is a protocol which exposes function in your browser javascript to LLM's as MCP tools.

For a more indepth understanding, refer here: https://mcp-b.ai/blogs

Live Demo

See MCP-B in action right away:

Examples

Check out our examples repository: MCP-B Examples

The examples repository contains:

• Vanilla TypeScript Demo: A simple todo app where MCP tools allow AI to manage tasks
• React Demo: Modern React application with MCP-B integration
• Script Tag Demo: The simplest integration - add MCP-B to any website using just a script tag

Community Examples

• Vue example By Besian
• Nuxt 3 example by Mike Chao

These demos highlight how MCP-B integrates into websites without needing complex setups. Install the MCP-B Chrome Extension to interact with the tools via the extension's chat interface or tool inspector.

What is MCP-B?

MCP-B extends the Model Context Protocol (MCP) with browser-specific transports, allowing your website to act as an MCP server. Websites expose existing functionality (e.g., APIs, forms, or state) as structured tools that AI agents can call directly.

Key components:

• Tab Transports: Use postMessage for communication between your website's MCP server and clients in the same tab.
• Extension Transports: Use Chrome's runtime messaging for communication with browser extensions.

This setup enables AI to interact with your site deterministically, respecting user authentication (e.g., session cookies) and scoping tools to specific pages or user states.

Quick Start

Get MCP-B running on your website in minutes. This guide focuses on adding an MCP server to expose tools, using the examples as a blueprint.

Prerequisites

• Node.js 22.12+ (check with node --version)
• pnpm 10+ (install via npm install -g pnpm)
• A website with JavaScript (vanilla, React, etc.)
• MCP-B Chrome Extension installed for testing

Development Setup (Repository Contributors)

If you want to contribute to MCP-B or run the examples locally:

1. Clone and install:

   git clone https://github.com/MiguelsPizza/WebMCP.git
   cd WebMCP
   pnpm install
   pnpm build:shared  # Build internal shared packages

   Note: Some postinstall scripts may fail initially - this is normal.

2. Configure your development extension ID (optional):

   # If your extension ID differs from the default
   cp apps/native-server/.env.example apps/native-server/.env
   # Edit apps/native-server/.env with your extension ID

3. Configure extension model provider and model name:

   # Create a .dev.vars file in apps/backend from the example
   cp apps/backend/.dev.vars.example apps/backend/.dev.vars
   # Edit apps/extension/.env with Open AI or Anthropic API Keys
   # ANTHROPIC_API_KEY="your_claude_api_key_here"

4. Start development:

   pnpm dev

   This automatically:

   • Builds all packages and native server
   • Registers native messaging host for both production and dev extension IDs
   • Starts WXT with persistent browser profile
   • Launches extension in Chrome with hot reload
   • Starts documentation website and all package watchers

5. Find your extension ID (if needed):

   • Open Chrome at chrome://extensions/
   • Enable "Developer mode"
   • Find your MCP-B extension and copy the ID
   • Update apps/native-server/.env with DEV_EXTENSION_ID=your-extension-id
   • Restart pnpm dev

6. Run examples - See the MCP-B Examples Repository for example applications.

Adding MCP-B to Your Existing Website

For adding MCP-B to your own project (recommended for most users):

Step 1: Install Dependencies

npm install @mcp-b/transports @modelcontextprotocol/sdk zod

Step 2: Add an MCP Server to Your Website

Create a single MCP server instance and connect it via Tab Transport. Expose tools that wrap your existing logic.

Example (vanilla JS/TypeScript):

import { TabServerTransport } from "@mcp-b/transports";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

// Create the server (one per site)
const server = new McpServer({
  name: "my-website",
  version: "1.0.0",
});

// Expose a tool (wrap your app's logic)
server.tool("getPageInfo", "Get current page info", {}, async () => {
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          title: document.title,
          url: window.location.href,
        }),
      },
    ],
  };
});

// Connect the transport
await server.connect(new TabServerTransport({ allowedOrigins: ["*"] })); // Adjust origins for security

• What this does: The server listens for clients (e.g., the extension injects one). Tools like getPageInfo become callable by AI.
• Tips: Use Zod for input schemas. Add visual feedback (e.g., notifications) so users see AI actions.

Step 3: Test It

1. Run your site (e.g., via a dev server).
2. Visit the page in Chrome with the MCP-B extension installed.
3. Open the extension popup:
   • Go to the "Tools" tab to see your exposed tools.
   • Use the chat interface to ask AI to call them (e.g., "Get the page info").
   • Or manually invoke via the inspector.

Step 4: Explore Examples

Check out the MCP-B Examples Repository for ready-to-run starters:

• vanilla-ts: Basic todo app. Tools: createTodo, getTodos, etc. Demonstrates dynamic tool registration and UI updates.
• react: Modern React application with hooks and state management integration.
• script-tag: Simple MCP-B integration using just a script tag - no build tools required.

Copy patterns from these examples to your site. Focus on wrapping client-side functions—e.g., use fetch with credentials: 'same-origin' for authenticated calls.

For more, see the documentation.

Using the Extension

The MCP-B extension acts as a client that discovers and routes calls to your website's MCP tools. Users can interact via a chat interface or tool inspector.

Option 1: Download from Chrome Web Store

Install the official release: MCP-B Extension.

Once installed:

1. Visit your MCP-enabled website.
2. Open the extension popup (click the icon in the toolbar).
3. Use the chat to query AI (e.g., "Add item to cart") or the inspector to list/call tools manually.

Option 2: Build from Source (Dev Build)

For the latest features or custom modifications:

1. Clone the repo: git clone https://github.com/MiguelsPizza/WebMCP.git.
2. Install: cd WebMCP && pnpm install && pnpm build:shared.
3. Build the extension: pnpm --filter @mcp-b/extension build.
4. Load in Chrome: Go to chrome://extensions/, enable Developer Mode, and load ./apps/extension/.output/chrome-mv3 unpacked.

Run in dev mode for hot reloading: pnpm --filter @mcp-b/extension dev.

Hooking Up the Native Server

To connect MCP-B to local MCP clients (e.g., Claude Desktop, Cursor) via a native server, bridging the browser to local processes:

IMPORTANT: You will need to disable the chrome webstore version of the extension if you have it downloaded. Failure to do so will cause port clashing when the dev and prod extension run

1. Install globally: npm install -g @mcp-b/native-server.
2. Run the host: @mcp-b/native-server (starts a server on port 12306 by default).

Add this configuration to your MCP client (e.g., in Claude's config or Cursor's .cursor/mcp.json):

{
  "type": "streamable-http",
  "url": "http://127.0.0.1:12306/mcp",
  "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
}

• What this does: The native server proxies requests from local clients to the browser extension, allowing tools from your website to be called from desktop apps.
• Note: The native server is based on mcp-chrome by hangwin. Ensure the extension is running and tabs with your site are open.

Test by running a local client (e.g., MCP Inspector) pointed at the URL, then calling tools from your site.

Advanced Usage

• Dynamic Tools: Register/unregister tools based on page or user state (e.g., admin-only tools in React components).
• Tool Caching: Annotate tools with { annotations: { cache: true } } to persist across tabs.
• Security: Tools run in your page's context—only expose what you'd allow via UI. Use MCP's elicitation for sensitive ops (support coming soon).

Repository Structure

WebMCP/
├── apps/                    # Application packages
│   ├── extension/          # Browser extension
│   ├── backend/            # Backend server (Cloudflare Workers)
│   └── native-server/      # Native messaging host
├── shared/                 # Internal shared packages
│   └── utils/             # Shared utility functions
└── e2e-tests/             # End-to-end tests

Related Repositories

• NPM Packages - Core npm packages (@mcp-b/transports, @mcp-b/mcp-react-hooks, etc.)
• Examples - Starter projects and demos
• Web Demo - Full-stack demo site with documentation
• WebMCP Userscripts - Tampermonkey scripts that inject MCP-B servers into popular websites

Troubleshooting

Common Setup Issues

Git clone times out:

# If the initial clone fails, complete it manually:
git clone https://github.com/MiguelsPizza/WebMCP.git
cd WebMCP
git pull origin main

Native server postinstall errors:

# These errors during pnpm install are normal and can be ignored:
# "Cannot find module '/path/to/apps/native-server/dist/scripts/postinstall.js'"
# The packages will still build correctly.

Example won't start: See the MCP-B Examples Repository for proper setup instructions.

Import resolution errors:

For monorepo development:

# Ensure the workspace is properly built:
pnpm build:shared  # Build internal shared packages
pnpm build:apps     # Build all applications
# Or run from the root with workspace support:
pnpm dev

For examples: See the MCP-B Examples Repository.

Port conflicts:

• Main dev server runs on port 5173-5174
• Extension dev server runs on port 3000
• Native host runs on port 12306

Extension Issues

Extension not detecting tools:

1. Ensure the extension is installed and enabled
2. Refresh the page after starting your MCP server
3. Check the extension popup "Tools" tab
4. Look for console errors in browser DevTools

Tools not working:

1. Verify your TabServerTransport configuration
2. Check that allowedOrigins includes your domain
3. Ensure tools are properly registered before transport connection

Development

git clone https://github.com/MiguelsPizza/WebMCP.git
cd WebMCP
pnpm install
pnpm build:shared  # Build internal shared packages first
pnpm dev  # Runs all in dev mode

Contributing

Contributions welcome! Focus on transports, examples, or docs. See CONTRIBUTING.md.

Security & Trust

• Respects browser sandbox and same-origin policy.
• No data collection; runs locally.
• Audit tool calls via the extension.

Roadmap

• Firefox/Safari support.
• Full MCP spec (beyond tools).
• Native host upstreaming.

Tutorial video

MCP-B lets your website become an MCP server, exposing functionality as tools that AI agents can call directly—using the browser's existing authentication and security model.

License

AGPL-3.0 - see LICENSE.

Created by Alexander Nahas (@miguelsPizza). Reach out: [email protected].

Website • GitHub