🚀 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"。
可用工具
- launch_browser：启动一个新的浏览器实例。
- navigate：跳转到指定URL。
- click_element：点击页面元素。
- type_text：在表单字段中输入文本。
- screenshot：捕获页面截图。
- get_element_text：从元素中提取文本。
- wait_for_element：等待元素出现或消失。
- evaluate_javascript：运行自定义JavaScript代码。
- get_console_logs：获取浏览器控制台日志（包括log、info、warn、error、debug）。
- analyze_screenshot：使用Gemma3（需要Ollama）进行AI截图分析。
- get_page_info：获取当前页面信息。
- close_browser：关闭浏览器实例。
- scroll：按指定方向（上/下/左/右）滚动页面。
- 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分析。该功能可以描述页面上可见的内容、分析页面结构，并根据上下文查找特定元素。
前提条件
- 安装Ollama：从 ollama.ai 下载。
- 安装Gemma3模型：
ollama pull gemma3:4b
- 启动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。如需商业许可咨询，请联系我们。