shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

claude-browser-mcp

一个基于Playwright的浏览器自动化MCP服务，提供网页导航、内容提取、表单填写和截图等标准化工具，支持多浏览器和高级功能如请求拦截和响应式测试。

article

README

🚀 浏览器MCP服务器

这是一个模型上下文协议（MCP）服务器，借助 Playwright 提供全面的浏览器自动化功能。该服务器允许AI助手通过标准化的MCP工具与网页进行交互，实现导航、内容提取、表单填充和截图捕获等操作。

🚀 快速开始

该服务器可让AI助手通过标准化的MCP工具与网页交互，实现导航、内容提取等功能。以下是快速开始的步骤：

安装

前提条件

  • Python 3.8 或更高版本
  • Node.js（用于安装Playwright浏览器）

从源代码安装

# 克隆仓库
git clone <repository-url>
cd claude-browser-mcp

# 安装依赖
pip install -e .

# 安装Playwright浏览器
playwright install

从PyPI安装（如果可用）

pip install claude-browser-mcp
playwright install

启动服务器

使用标准输入输出传输启动服务器：

browser-mcp
# 或者
python -m src.server

配置

通过环境变量配置浏览器：

export BROWSER_HEADLESS=true          # 以无头模式运行
export BROWSER_TYPE=chromium          # 浏览器类型（chromium/firefox/webkit）
export BROWSER_TIMEOUT=30000          # 默认超时时间（毫秒）

MCP客户端集成

添加到您的MCP客户端配置中：

{
  "mcpServers": {
    "browser-automation": {
      "command": "browser-mcp",
      "args": []
    }
  }
}

✨ 主要特性

核心浏览器操作

  • 导航到URL：采用智能等待策略
  • 提取页面内容：可使用自定义选择器
  • 截图：支持全页、视口或特定元素截图
  • 执行JavaScript：并捕获结果
  • 点击元素：通过CSS选择器
  • 自动填充表单：并进行验证

高级功能

  • 多浏览器支持：（Chromium、Firefox、WebKit）
  • 请求拦截和监控
  • 视口定制和响应式测试
  • 链接提取和URL处理
  • 错误处理：提供详细响应
  • 资源管理和清理

📦 安装指南

前提条件

  • Python 3.8 或更高版本
  • Node.js（用于安装Playwright浏览器）

从源代码安装

# 克隆仓库
git clone <repository-url>
cd claude-browser-mcp

# 安装依赖
pip install -e .

# 安装Playwright浏览器
playwright install

从PyPI安装（如果可用）

pip install claude-browser-mcp
playwright install

💻 使用示例

基础用法

作为MCP服务器启动

browser-mcp
# 或者
python -m src.server

配置浏览器

export BROWSER_HEADLESS=true          # 以无头模式运行
export BROWSER_TYPE=chromium          # 浏览器类型（chromium/firefox/webkit）
export BROWSER_TIMEOUT=30000          # 默认超时时间（毫秒）

MCP客户端集成

{
  "mcpServers": {
    "browser-automation": {
      "command": "browser-mcp",
      "args": []
    }
  }
}

高级用法

可用工具示例

navigate_to

导航到指定URL，并可选择等待。

{
  "name": "navigate_to",
  "arguments": {
    "url": "https://example.com",
    "wait_for": "selector", 
    "timeout": 30
  }
}
get_page_content

从当前页面提取文本内容。

{
  "name": "get_page_content", 
  "arguments": {
    "include_links": true,
    "selector": ".main-content"
  }
}
click_element

通过CSS选择器点击元素。

{
  "name": "click_element",
  "arguments": {
    "selector": "button#submit",
    "timeout": 10
  }
}
fill_form

用数据填充表单字段。

{
  "name": "fill_form",
  "arguments": {
    "fields": {
      "#email": "user@example.com",
      "#password": "secretpass"
    },
    "submit": true
  }
}
take_screenshot

捕获页面截图。

{
  "name": "take_screenshot",
  "arguments": {
    "full_page": true,
    "selector": ".dashboard"
  }
}
execute_javascript

在浏览器上下文中运行JavaScript。

{
  "name": "execute_javascript", 
  "arguments": {
    "code": "document.title",
    "return_value": true
  }
}

📚 详细文档

项目结构

claude-browser-mcp/
├── src/
│   ├── __init__.py          # 包初始化
│   ├── server.py            # MCP服务器实现
│   ├── browser.py           # 浏览器管理
│   ├── actions.py           # 高级浏览器操作
│   └── utils.py             # 实用函数
├── requirements.txt         # Python依赖
├── setup.py                 # 包配置
└── README.md               # 本文件

架构

服务器 (server.py)

  • 实现MCP服务器并注册工具
  • 请求路由和响应格式化
  • 错误处理和日志记录
  • 异步工具执行

浏览器管理器 (browser.py)

  • 管理Playwright浏览器的生命周期
  • 创建和配置上下文
  • 资源清理和恢复
  • 多浏览器支持

操作 (actions.py)

  • 高级浏览器自动化方法
  • 内容提取和处理
  • 表单交互和验证
  • 截图和JavaScript执行

实用工具 (utils.py)

  • HTML清理和净化
  • URL验证和规范化
  • 图像处理和编码
  • 数据格式化实用工具

🔧 技术细节

安全考虑

  • HTML净化：去除危险脚本和属性
  • URL验证：防止恶意重定向
  • 输入验证：对所有用户提供的数据进行验证
  • 资源限制：防止过度使用内存
  • 超时控制：防止操作挂起

Docker部署

使用Docker快速启动

# 使用Docker Compose构建并运行
docker-compose up browser-mcp

# 或者手动构建
./scripts/docker-build.sh
./scripts/start-container.sh

生产部署

# 构建生产镜像
docker build -t browser-mcp:latest .

# 使用优化设置运行
docker run -d \
  --name browser-mcp \
  --init --ipc=host --shm-size=1gb \
  --memory=2g --cpus=1.0 \
  -v $(pwd)/screenshots:/app/screenshots \
  -v $(pwd)/downloads:/app/downloads \
  browser-mcp:latest

使用Docker进行开发

# 带有调试功能的开发容器
docker-compose --profile dev up browser-mcp-dev

# 进入容器
docker exec -it claude-browser-mcp-dev /bin/bash

容器管理

# 健康检查
./scripts/health-check.sh

# 查看日志
docker logs -f claude-browser-mcp

# 监控资源
docker stats claude-browser-mcp

错误处理

服务器提供详细的错误响应，包括：

  • 错误分类：（超时、验证、执行）
  • 上下文信息：（URL、选择器、参数）
  • 恢复建议：在适用的情况下
  • 日志记录：用于调试和监控

响应格式

所有工具返回标准化的JSON响应：

{
  "success": true,
  "url": "https://example.com",
  "title": "页面标题",
  "data": "...",
  "metadata": {
    "timestamp": "...",
    "execution_time": "..."
  }
}

错误响应包括：

{
  "success": false,
  "error": "详细错误消息",
  "tool": "工具名称",
  "arguments": {...},
  "timestamp": "..."
}

环境变量

| 属性 | 详情 | |------|------| | BROWSER_HEADLESS | true | 以无头模式运行浏览器 | | BROWSER_TYPE | chromium | 使用的浏览器引擎 | | BROWSER_TIMEOUT | 30000 | 默认超时时间（毫秒） |

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

🙏 致谢

📞 支持

  • 问题反馈：在GitHub上报告错误和请求功能
  • 文档查阅：查看代码内的文档
  • 社区交流：加入MCP社区讨论

注意：这是一个基础实现。根据具体用例，可以添加更多功能，如请求拦截、高级表单处理和性能优化。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端