MCP Browser Server

AutoProbeMCP - 为你的 Agent 提供浏览器

一个使用 Playwright 提供浏览器自动化功能的 Model Context Protocol（MCP）服务。 此服务通过标准化接口，让 AI 助手能够与网页交互。

非常适合使用 AI 助手执行网页自动化、测试和调试工作流，包括：

• Chat.fans agents - 在 VS Code 中为 AI Agent 提供网页交互能力
• 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 集成

在 settings.json 或工作区配置中添加配置，以便在 VS Code 中配置 MCP 服务：

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

配置完成后，Chat.fans agents 和 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 进行 AI 截图分析（需要 Ollama）
11. get_page_info - 获取当前页面信息
12. close_browser - 关闭浏览器实例
13. scroll - 按指定方向（上/下/左/右）滚动页面
14. check_scrollability - 检查页面是否可以向指定方向滚动

示例：Web 应用测试

// Launch browser in headed mode for visual debugging
await launch_browser({ browser: "chromium", headless: false });

// Navigate to login page
await navigate({ url: "http://localhost:3000/login" });

// Fill in credentials
await type_text({ selector: "input[type='email']", text: "[email protected]" });
await type_text({ selector: "input[type='password']", text: "password123" });

// Submit form
await click_element({ selector: "button[type='submit']" });

// Wait for successful login
await wait_for_element({ selector: ".dashboard", timeout: 10000 });

// Check for any console errors during login
await get_console_logs({ level: "error" });

// Take screenshot of dashboard
await screenshot({ fullPage: true, path: "dashboard.png" });

// Get all console logs for debugging
await get_console_logs();

// Scroll down to see more content
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

// Check if page can be scrolled vertically
await check_scrollability({ direction: "vertical" });

// Scroll back to top
await scroll({ direction: "up", pixels: 500 });

页面滚动和导航

MCP Browser Server 包含全面的滚动工具，可用于浏览长页面并检查滚动能力：

滚动工具

scroll 工具支持以精细控制向任意方向滚动页面：

// Scroll down by default amount (100px)
await scroll();

// Scroll in specific directions with custom distances
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 });

// Smooth scrolling for better user experience
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

参数：

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

可滚动性检查工具

check_scrollability 工具用于判断页面是否可以向指定方向滚动：

// Check both vertical and horizontal scrollability
await check_scrollability({ direction: "both" });

// Check only vertical scrolling
await check_scrollability({ direction: "vertical" });

// Check only horizontal scrolling  
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
   

使用示例

基本截图分析

// Take and analyze a screenshot with AI
await analyze_screenshot({ 
  fullPage: true,
  model: "gemma3:4b"
});

详细结构分析

// Get detailed analysis of page structure
await analyze_screenshot({ 
  detailed: true,
  pretext: "Focus on navigation elements and form fields"
});

特定上下文分析

// Look for specific elements or issues
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 安装中可用的任何其他视觉模型

开发与测试

快速设置

# One-command setup (installs dependencies, browsers, and builds)
npm run setup

# Or step by step:
npm install
npx playwright install
npm run build

开发命令

# Build the project
npm run build

# Run in development mode
npm run dev

# Start the server
npm run start

# Development helper (shows all available commands)
npm run dev-helper help

测试

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

# Run basic communication test
npm run test

# Run browser automation demo
npm run test:demo

# Run AI analysis test (requires Ollama)
npm run test:ai-simple

# Check system status
npm run test:status

# Run all tests
npm run test:all

开发辅助工具

使用开发辅助工具处理常见任务：

# Show all available commands
npm run dev-helper help

# Quick setup from scratch
npm run dev-helper setup

# Run comprehensive tests
npm run dev-helper test

# Clean generated files
npm run dev-helper clean

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

项目结构

mcp-browser-server/
├── src/                 # TypeScript source code
│   └── index.ts        # Main MCP server implementation
├── build/              # Compiled JavaScript output
├── tests/              # Test scripts and documentation
│   ├── README.md       # Testing documentation
│   ├── simple-test.mjs # Basic communication test
│   ├── demo-test.mjs   # Browser automation demo
│   └── *.mjs          # Additional test files
├── screenshots/        # Generated screenshots from tests
├── package.json        # Project configuration
└── README.md          # This file

许可证

双重许可：

• 个人用途：可免费用于个人、教育和非商业用途
• 商业用途：需另行获得商业许可

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