[!IMPORTANT] 🚨 WebMCP API 已被接受为 W3C 交付成果，并正在过渡到官方 Web 标准开发。社区及所有相关工作已移至 WebMCP explainer repository。请在那里加入我们！🚨

[!IMPORTANT] 📝 仓库状态：MCP-B 扩展不再开源。此仓库代表代码库的旧版本，仅用于历史参考。所有开源内容（传输层等）已移植到 WebMCP Github Org。

WebMCP:

🚀 快速开始 • ✨ 实时演示 • 📚 文档 • 🤝 贡献

加入我们的社区

协议

WebMCP 是 MCP-B 实现的底层协议。它是一个将浏览器 JavaScript 中的函数暴露给大型语言模型 (LLM) 作为 MCP 工具的协议。

欲深入了解，请参考此处：https://mcp-b.ai/blogs

实时演示

立即查看 MCP-B 的实际运行效果：

示例

查看我们的示例仓库：MCP-B 示例

该示例仓库包含：

• 原生 TypeScript 演示：一个简单的待办事项应用，其中 MCP 工具允许 AI 管理任务
• React 演示：集成了 MCP-B 的现代 React 应用程序
• 脚本标签演示：最简单的集成方式——仅使用一个脚本标签即可将 MCP-B 添加到任何网站

社区示例

• Vue 示例 由 Besian 提供
• Nuxt 3 示例 由 Mike Chao 提供

这些演示突出了 MCP-B 如何集成到网站中而无需复杂的设置。安装 MCP-B Chrome 扩展 以通过扩展的聊天界面或工具检查器与工具进行交互。

什么是 MCP-B？

MCP-B 使用针对浏览器的传输层 (Transports) 扩展了模型上下文协议 (Model Context Protocol, MCP)，允许您的网站充当 MCP 服务器。网站将现有功能（例如 API、表单或状态）暴露为结构化工具，AI 代理可以直接调用它们。

关键组件：

• 标签页传输层 (Tab Transports)：使用 postMessage 在同一标签页内您的网站 MCP 服务器和客户端之间进行通信。
• 扩展传输层 (Extension Transports)：使用 Chrome 的运行时消息传递与浏览器扩展进行通信。

此设置使 AI 能够确定性地与您的站点交互，尊重用户身份验证（例如会话 Cookie），并将工具范围限定在特定页面或用户状态。

快速开始

几分钟内即可让您的网站运行 MCP-B。本指南侧重于添加 MCP 服务器以暴露工具，并以示例为蓝图。

前置条件

• Node.js 22.12+ (使用 node --version 检查)
• pnpm 10+ (通过 npm install -g pnpm 安装)
• 带有 JavaScript 的网站（原生、React 等）
• 已安装 MCP-B Chrome 扩展 用于测试

开发环境设置（仓库贡献者）

如果您想为 MCP-B 做贡献或在本地运行示例：

1. 克隆并安装：

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

   注意：某些 postinstall 脚本最初可能会失败——这是正常的。

2. 配置您的开发扩展 ID（可选）：

   # 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. 配置扩展模型提供者和模型名称：

   # 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. 启动开发：

   pnpm dev
   

   这将自动：

   • 构建所有包和本地服务器
   • 为生产环境和开发环境扩展 ID 注册原生消息传递主机
   • 启动带有持久化浏览器配置的 WXT
   • 在 Chrome 中启动扩展并启用热重载
   • 启动文档网站和所有包监听器

5. 查找您的扩展 ID（如果需要）：

   • 在 chrome://extensions/ 打开 Chrome
   • 启用“开发者模式”
   • 找到您的 MCP-B 扩展并复制 ID
   • 使用 DEV_EXTENSION_ID=your-extension-id 更新 apps/native-server/.env
   • 重启 pnpm dev

6. 运行示例 - 参见 MCP-B 示例仓库 获取示例应用程序。

将 MCP-B 添加到您的现有网站

要将 MCP-B 添加到您自己的项目中（推荐给大多数用户）：

步骤 1：安装依赖项

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

步骤 2：向您的网站添加 MCP 服务器

创建一个单一的 MCP（模型上下文协议）服务器实例，并通过 Tab Transport（标签传输）连接它。暴露封装您现有逻辑的工具。

示例（原生 JavaScript/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

• 作用：服务器监听客户端（例如，扩展会注入一个）。像 getPageInfo 这样的工具可由 AI 调用。
• 提示：使用 Zod 进行输入模式定义。添加视觉反馈（例如通知），以便用户看到 AI 操作。

步骤 3：测试它

1. 运行您的站点（例如，通过开发服务器）。
2. 在安装了 MCP-B 扩展程序的 Chrome 中访问该页面。
3. 打开扩展程序弹出窗口：
   • 转到“工具”选项卡以查看您暴露的工具。
   • 使用聊天界面要求 AI 调用它们（例如，“获取页面信息”）。
   • 或通过检查器手动调用。

步骤 4：探索示例

查看 MCP-B 示例仓库 以获取现成的启动项目：

• vanilla-ts：基础待办事项应用。工具：createTodo、getTodos 等。演示动态工具注册和 UI 更新。
• react：集成了 hooks 和状态管理的现代 React 应用程序。
• script-tag：仅使用脚本标签即可实现的简单 MCP-B 集成——无需构建工具。

从这些示例中复制模式到您的站点。专注于封装客户端函数——例如，对于认证调用，使用带有 credentials: 'same-origin' 的 fetch。

更多详情，请参阅 文档。

使用扩展程序

MCP-B 扩展程序充当客户端，发现并将调用路由到您网站的 MCP 工具。用户可以通过聊天界面或工具检查器进行交互。

选项 1：从 Chrome 应用商店下载

安装官方版本：MCP-B 扩展程序。

安装后：

1. 访问您的 MCP 启用网站。
2. 打开扩展程序弹出窗口（点击工具栏中的图标）。
3. 使用聊天查询 AI（例如，“将商品添加到购物车”）或使用检查器列出/手动调用工具。

选项 2：从源代码构建（开发版）

用于获取最新功能或自定义修改：

1. 克隆仓库：git clone https://github.com/MiguelsPizza/WebMCP.git。
2. 安装：cd WebMCP && pnpm install && pnpm build:shared。
3. 构建扩展程序：pnpm --filter @mcp-b/extension build。
4. 在 Chrome 中加载：转到 chrome://extensions/，启用开发者模式，并加载 ./apps/extension/.output/chrome-mv3 解压文件。

以开发模式运行以实现热重载：pnpm --filter @mcp-b/extension dev。

连接本地服务器

要通过本地服务器将 MCP-B 连接到本地 MCP 客户端（例如 Claude Desktop、Cursor），桥接浏览器和本地进程：

重要提示：如果您已下载了 Chrome 应用商店版本的扩展程序，您将需要禁用它。 如果不这样做，当开发和生产扩展程序运行时会导致端口冲突。

1. 全局安装：npm install -g @mcp-b/native-server。
2. 运行主机：@mcp-b/native-server（默认情况下在 12306 端口启动服务器）。

将此配置添加到您的 MCP 客户端（例如，在 Claude 的配置或 Cursor 的 .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"
}

• 作用：本地服务器将来自本地客户端的请求代理到浏览器扩展程序，允许从桌面应用程序调用您网站上的工具。
• 注意：本地服务器基于 hangwin 的 mcp-chrome。确保扩展程序正在运行且打开了包含您站点的标签页。

通过运行指向该 URL 的本地客户端（例如 MCP Inspector），然后调用您站点的工具进行测试。

高级用法

• 动态工具：根据页面或用户状态注册/注销工具（例如，React 组件中的仅限管理员工具）。
• 工具缓存：注释工具 { annotations: { cache: true } } 以跨标签页持久化。
• 安全性：工具在您的页面上下文中运行——只暴露您允许 UI 的内容。使用 MCP 的 elicitation（询问）处理敏感操作（支持即将推出）。

仓库结构

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

相关仓库

• NPM Packages - 核心 npm 包 (@mcp-b/transports, @mcp-b/mcp-react-hooks 等)
• Examples - 启动项目和演示
• Web Demo - 带有文档的全栈演示站点
• WebMCP Userscripts - 将 MCP-B 服务器注入流行网站的 Tampermonkey 脚本

故障排除

常见设置问题

Git 克隆超时：

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

本地服务器 postinstall 错误：

# 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.

示例无法启动： 请查看 MCP-B 示例仓库 以获取正确的设置说明。

导入解析错误：

对于 Monorepo（单体仓库）开发：

# Ensure the workspace is properly built:
pnpm build:shared  # Build internal shared packages
pnpm build:apps     # Build all applications

或者从根目录运行，支持工作区：

pnpm dev

示例：请参阅 MCP-B 示例仓库。

端口冲突：

• 主开发服务器运行在端口 5173-5174
• 扩展开发服务器运行在端口 3000
• 原生主机运行在端口 12306

扩展问题

扩展未检测到工具：

1. 确保扩展已安装并启用
2. 启动您的 MCP（模型上下文协议）服务器后刷新页面
3. 检查扩展弹出窗口的“工具”标签页
4. 在浏览器开发者工具 (DevTools) 中查找控制台错误

工具无法工作：

1. 验证您的 TabServerTransport 配置
2. 检查 allowedOrigins 是否包含您的域名
3. 确保在传输连接之前正确注册了工具

开发

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.md。

安全与信任

• 尊重浏览器沙箱 (browser sandbox) 和同源策略 (same-origin policy)。
• 无数据收集；本地运行。
• 通过扩展审计工具调用。

路线图

• Firefox/Safari 支持。
• 完整的 MCP 规范（超越工具）。
• 原生主机功能合并至上游项目。

教程视频

MCP-B 允许您的网站成为 MCP 服务器，将功能暴露为 AI 代理可以直接调用的工具——利用浏览器现有的认证和安全模型。

许可证

AGPL-3.0 - 参见 LICENSE。

由 Alexander Nahas 创建 (@miguelsPizza)。联系方式：alexnahasdev@gmail.com。

网站 • GitHub

WebMCP 快速上手指南

WebMCP 是一种底层协议，通过 MCP-B 实现，可将浏览器中的 JavaScript 功能暴露为大语言模型的 MCP 工具。这使得 AI 能够直接调用网站现有的功能（如 API、表单或状态）。

注意：相关开源内容已迁移至 WebMCP Github Org，本指南基于当前可用的 NPM 包进行集成。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 22.12+ (可通过 node --version 检查)
• 包管理器: pnpm 10+ (可通过 npm install -g pnpm 安装)
• 浏览器: Google Chrome
• 扩展程序: 安装 MCP-B Chrome Extension 用于测试

安装步骤

将 MCP-B 集成到您的现有网站项目中，首先安装必要的依赖包：

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

基本使用

创建一个 MCP 服务器实例，并通过 Tab Transport 连接，暴露您网站的逻辑作为 AI 可调用的工具。

1. 创建服务器并注册工具

在您的网站入口文件（如 index.ts 或 main.tsx）中添加以下代码：

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

// 创建服务器（每个站点一个实例）
const server = new McpServer({
  name: "my-website",
  version: "1.0.0",
});

// 暴露工具（封装您的应用逻辑）
server.tool("getPageInfo", "Get current page info", {}, async () => {
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          title: document.title,
          url: window.location.href,
        }),
      },
    ],
  };
});

// 连接传输层
await server.connect(new TabServerTransport({ allowedOrigins: ["*"] })); // 根据安全需求调整 origins

2. 运行与测试

1. 启动您的网站开发服务器。
2. 在 Chrome 中访问该页面，确保已安装 MCP-B 扩展。
3. 打开扩展程序的弹出窗口：
   • 切换到 "Tools" 标签页查看已暴露的工具。
   • 使用聊天界面让 AI 调用工具（例如输入："Get the page info"）。
   • 或通过 Inspector 手动调用工具。

进阶参考

• 更多示例: 查看 MCP-B Examples Repository 获取 React、Vue 等框架的集成模板。
• 本地客户端连接: 如需连接 Claude Desktop 等本地 MCP 客户端，可安装全局原生服务器 npm install -g @mcp-b/native-server 并配置 URL 指向 http://127.0.0.1:12306/mcp。