MCP Browser Server

🚀 MCP浏览器服务器

MCP浏览器服务器是一个基于模型上下文协议（MCP）的服务器，借助Playwright实现浏览器自动化功能。该服务器能让AI助手通过标准化接口与网页进行交互，在网页自动化、测试和调试工作流中表现出色。

它适用于各类AI助手，包括：

• Chat.fans 代理：为VS Code中的AI代理赋予网页交互能力。
• GitHub Copilot Chat：通过浏览器自动化提升开发工作流程效率。
• 任何支持MCP的AI助手：为AI工具提供通用的浏览器自动化功能。

✨ 主要特性

• 多浏览器支持：兼容Chromium、Firefox和WebKit浏览器。
• 全面自动化：支持导航、点击、输入、截图等操作。
• JavaScript执行：可在浏览器上下文中运行自定义脚本。
• 元素交互：等待元素加载、获取文本内容并与表单交互。
• 截图功能：能够捕获全页或视口截图。
• 类型安全：采用TypeScript构建，并使用Zod进行运行时验证。

📦 安装指南

安装项目依赖

npm install
npm run build

安装Playwright浏览器

npx playwright install

安装系统依赖（Linux）

sudo npx playwright install-deps

💻 使用示例

VS Code集成

在VS Code中配置MCP服务器，可将以下内容添加到settings.json或工作区配置中：

"mcp": {
    "servers": {
      "browser-automation": {
        "command": "node",
        "args": [
          "/home/yourUserName/mcp-browser-server/build/index.js"
        ],
        "env": {}
      }
    }
  }

配置完成后，Chat.fans代理和GitHub Copilot Chat即可使用浏览器自动化工具进行网页测试、数据抓取和自动化任务。

可用的VS Code任务

• 构建：按下 Ctrl+Shift+P，选择 "Tasks: Run Task"，然后选择 "build"。
• 开发模式：按下 Ctrl+Shift+P，选择 "Tasks: Run Task"，然后选择 "dev"。
• 测试MCP服务器：按下 Ctrl+Shift+P，选择 "Tasks: Run Task"，然后选择 "test-mcp-server"。

可用工具

1. launch_browser：启动一个新的浏览器实例。
2. navigate：跳转到指定URL。
3. click_element：点击页面元素。
4. type_text：在表单字段中输入文本。
5. screenshot：捕获页面截图。
6. get_element_text：从元素中提取文本。
7. wait_for_element：等待元素出现或消失。
8. evaluate_javascript：运行自定义JavaScript代码。
9. get_console_logs：获取浏览器控制台日志（包括log、info、warn、error、debug）。
10. analyze_screenshot：使用Gemma3（需要Ollama）进行AI截图分析。
11. get_page_info：获取当前页面信息。
12. close_browser：关闭浏览器实例。
13. scroll：按指定方向（上/下/左/右）滚动页面。
14. check_scrollability：检查页面在特定方向上是否可滚动。

基础用法

以下是一个网页应用测试的示例：

// 以有头模式启动浏览器，便于可视化调试
await launch_browser({ browser: "chromium", headless: false });

// 导航到登录页面
await navigate({ url: "http://localhost:3000/login" });

// 填写凭证
await type_text({ selector: "input[type='email']", text: "user@example.com" });
await type_text({ selector: "input[type='password']", text: "password123" });

// 提交表单
await click_element({ selector: "button[type='submit']" });

// 等待登录成功
await wait_for_element({ selector: ".dashboard", timeout: 10000 });

// 检查登录期间是否有控制台错误
await get_console_logs({ level: "error" });

// 截取仪表盘截图
await screenshot({ fullPage: true, path: "dashboard.png" });

// 获取所有控制台日志进行调试
await get_console_logs();

// 向下滚动以查看更多内容
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

// 检查页面是否可以垂直滚动
await check_scrollability({ direction: "vertical" });

// 滚动回顶部
await scroll({ direction: "up", pixels: 500 });

高级用法

页面滚动和导航

MCP浏览器服务器提供了全面的滚动工具，用于导航长页面和检查滚动能力。

滚动工具

scroll 工具允许你以细粒度控制页面在任何方向上滚动：

// 默认向下滚动100px
await scroll();

// 按指定方向和自定义距离滚动
await scroll({ direction: "down", pixels: 300, behavior: "smooth" });
await scroll({ direction: "up", pixels: 200, behavior: "auto" });
await scroll({ direction: "left", pixels: 150 });
await scroll({ direction: "right", pixels: 150 });

// 平滑滚动以提升用户体验
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

参数说明：

• direction：可选值为 "up"、"down"、"left"、"right"（默认值为 "down"）。
• pixels：滚动的像素数（默认值为100）。
• behavior：可选值为 "auto" 或 "smooth"（默认值为 "auto"）。

滚动能力检查工具

check_scrollability 工具用于确定页面是否可以在特定方向上滚动：

// 检查垂直和水平滚动能力
await check_scrollability({ direction: "both" });

// 仅检查垂直滚动能力
await check_scrollability({ direction: "vertical" });

// 仅检查水平滚动能力
await check_scrollability({ direction: "horizontal" });

响应内容包括：

• 当前滚动位置。
• 最大滚动距离。
• 每个方向上是否可以滚动。
• 详细的位置信息。

AI截图分析

analyze_screenshot 工具通过Ollama使用本地Gemma3模型对网页进行AI分析。该功能可以描述页面上可见的内容、分析页面结构，并根据上下文查找特定元素。

前提条件

1. 安装Ollama：从 ollama.ai 下载。
2. 安装Gemma3模型：

ollama pull gemma3:4b

3. 启动Ollama服务：

ollama serve

使用示例

// 基本截图分析
await analyze_screenshot({ 
  fullPage: true,
  model: "gemma3:4b"
});

// 详细结构分析
await analyze_screenshot({ 
  detailed: true,
  pretext: "Focus on navigation elements and form fields"
});

// 特定上下文分析
await analyze_screenshot({ 
  pretext: "Check if there are any error messages or broken layouts",
  path: "error-check.png"
});

参数说明：

• fullPage（布尔值）：是否捕获整个可滚动页面，而非仅视口。
• path（字符串）：可选的截图保存文件路径。
• pretext（字符串）：为AI提供的额外上下文或特定指令。
• model（字符串）：使用的AI模型（默认值为 "gemma3:4b"）。
• detailed（布尔值）：是否请求详细的结构分析。

支持的模型：

• gemma3:4b（默认，速度和质量平衡较好）。
• 任何在你的Ollama安装中可用的具备视觉能力的模型。

📚 详细文档

开发与测试

快速设置

# 一键设置（安装依赖、浏览器并构建项目）
npm run setup

# 或分步操作
npm install
npx playwright install
npm run build

开发命令

# 构建项目
npm run build

# 以开发模式运行
npm run dev

# 启动服务器
npm run start

# 开发助手（显示所有可用命令）
npm run dev-helper help

测试

项目在 tests/ 目录中包含了全面的测试：

# 运行基本通信测试
npm run test

# 运行浏览器自动化演示
npm run test:demo

# 运行AI分析测试（需要Ollama）
npm run test:ai-simple

# 检查系统状态
npm run test:status

# 运行所有测试
npm run test:all

开发助手

使用开发助手进行常见任务：

# 显示所有可用命令
npm run dev-helper help

# 从头开始快速设置
npm run dev-helper setup

# 运行全面测试
npm run dev-helper test

# 清理生成的文件
npm run dev-helper clean

更多测试详情，请参阅 tests/README.md。

项目结构

mcp-browser-server/
├── src/                 # TypeScript源代码
│   └── index.ts        # 主MCP服务器实现
├── build/              # 编译后的JavaScript输出
├── tests/              # 测试脚本和文档
│   ├── README.md       # 测试文档
│   ├── simple-test.mjs # 基本通信测试
│   ├── demo-test.mjs   # 浏览器自动化演示
│   └── *.mjs          # 其他测试文件
├── screenshots/        # 测试生成的截图
├── package.json        # 项目配置
└── README.md          # 本文件

📄 许可证

双重许可：

• 个人使用：免费用于个人、教育和非商业用途。
• 商业使用：需要单独的商业许可证。

完整条款请参阅 LICENSE。如需商业许可咨询，请联系我们。