Claude Browser MCP

🚀 浏览器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": "..."
}

环境变量

📄 许可证

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

🙏 致谢

• Playwright：提供浏览器自动化功能
• MCP：提供协议规范
• Anthropic：进行Claude和MCP开发

📞 支持

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

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