AI导哈

浏览器自动化控制器

一个通过MCP协议集成的浏览器自动化解决方案，提供隐身模式和Cloudflare绕过等高级功能，适用于AI代理的浏览器操作。

  • by bgunduz55
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 bgunduz55/browser-controller-mcp

使用说明

浏览器控制器MCP

通过MCP（模型上下文协议）集成，提供一个全面的浏览器自动化解决方案。此项目包括一个Chrome扩展和一个MCP服务器，它们协同工作，为AI代理提供强大的浏览器自动化能力，包括隐身模式和Cloudflare绕过功能。

🚀 特性

  • MCP协议支持完全符合MCP规范
  • Chrome 扩展程序具备隐身功能的真实浏览器自动化
  • WebSocket 通信实时双向通信
  • 绕过Cloudflare高级机器人检测规避
  • 隐身模式指纹随机化与类人行为
  • 命令队列带有重试逻辑的稳健命令管理
  • 多客户端支持同时处理多个AI代理
  • 全面日志记录带有多级结构的日志记录
  • 速率限制内置滥用防护

📁 项目结构

browser-controller-mcp/
├── README.md                    # This file
├── browser-extension/           # Chrome Extension
│   ├── manifest.json          # Extension manifest
│   ├── background.js          # Service worker
│   ├── content.js            # Content script
│   ├── popup/                # Extension popup UI
│   │   ├── popup.html
│   │   ├── popup.js
│   │   └── popup.css
│   ├── lib/                  # Utility libraries
│   │   └── stealth.js       # Stealth mode implementation
│   ├── config/              # Configuration
│   │   └── config.json
│   ├── icons/               # Extension icons
│   │   ├── icon16.svg
│   │   ├── icon48.svg
│   │   └── icon128.svg
│   ├── package.json
│   └── README.md
│
└── browser-mcp-server/        # MCP Server
    ├── src/                   # TypeScript source
    │   ├── index.ts          # Entry point
    │   ├── server.ts         # WebSocket/HTTP server
    │   ├── types/            # TypeScript types
    │   ├── handlers/         # Command handlers
    │   ├── state/            # State management
    │   ├── auth/             # Authentication
    │   ├── utils/            # Utility functions
    │   └── migration/        # Migration generator
    ├── tests/                # Test suite
    ├── config/               # Configuration files
    ├── package.json
    ├── tsconfig.json
    └── README.md

🛠️ 安装

先决条件

  • Node.js 18及以上版本
  • Chrome 浏览器
  • npm 或 yarn

快速入门

  1. 克隆仓库

    git clone <repository-url>
cd browser-controller-mcp

  2. 设置MCP服务器

    cd browser-mcp-server
npm install
npm run build
npm start

  3. 加载Chrome扩展程序

    • 打开Chrome浏览器并导航至 chrome://extensions/
    • 启用“开发者模式”
    • 点击“加载未打包扩展”并选择 browser-extension 文件夹

  4. 配置光标MCP（或：设置光标MCP） 添加到你的光标（或：添加到你的光标位置） mcp.json：

    {
  "mcpServers": {
    "browser-controller": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {}
    }
  }
}

🎯 使用方法

基本浏览器自动化

// Navigate to a website
await mcp.call('browser_navigate', {
  url: 'https://example.com',
  bypassCloudflare: true,
  waitUntil: 'load'
});

// Click an element
await mcp.call('browser_click', {
  selector: '.button',
  humanLike: true
});

// Extract data
const data = await mcp.call('browser_extract_data', {
  selector: '.content',
  includeText: true
});

// Take screenshot
await mcp.call('browser_screenshot', {
  fullPage: false,
  format: 'png'
});

高级功能

// Wait for specific conditions
await mcp.call('browser_wait', {
  type: 'selector',
  value: '.loaded-content',
  timeout: 30000
});

// Analyze page structure
const analysis = await mcp.call('browser_analyze_page', {});

🔧 配置

MCP服务器配置

创建 browser-mcp-server/config/server.config.json:

{
  "server": {
    "port": 8080,
    "host": "localhost",
    "secure": false
  },
  "websocket": {
    "heartbeatInterval": 30000,
    "connectionTimeout": 60000
  },
  "authentication": {
    "enabled": true,
    "apiKeyLength": 32
  },
  "rateLimit": {
    "enabled": true,
    "maxRequests": 100,
    "windowMs": 60000
  }
}

扩展配置

该扩展程序会自动连接到 ws://localhost:8080/ws您可以通过弹出界面修改连接设置，或者通过更新配置来实现 background.js。

🧪 测试

MCP服务器测试

cd browser-mcp-server
npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests
npm run test:e2e          # End-to-end tests

扩展测试

  • 使用 Chrome DevTools 调试扩展程序
  • 在网络选项卡中监控 WebSocket 连接
  • 检查控制台日志以获取调试信息
  • 使用弹出界面监控实时状态

🚀 部署

发展

# Start MCP Server in development mode
cd browser-mcp-server
npm run dev

# Load extension in Chrome
# chrome://extensions/ -> Load unpacked -> select browser-extension folder

生产

# Build and start MCP Server
cd browser-mcp-server
npm run build
npm start

# Extension runs directly from source (no build required)

Docker

# MCP Server Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY config/ ./config/
EXPOSE 8080
CMD ["node", "dist/index.js"]

📊 监控

健康检查

curl http://localhost:8080/health

指标

  • 活跃连接
  • 每分钟指令数
  • 成功率
  • 平均响应时间
  • 按类型划分的错误率

记录日志

带有级别的结构化日志记录：

  • debug详细的调试信息
  • info一般信息
  • warn警告信息
  • error错误信息

🔒 安全

认证

  • 基于API密钥的身份验证
  • 可配置的密钥长度和过期时间
  • 每个客户端的速率限制

网络安全

  • CORS 配置
  • WebSocket源验证
  • 请求大小限制

数据保护

  • 不记录敏感数据
  • 安全的WebSocket连接
  • 输入验证和清理

🐛 故障排除

常见问题

  1. 连接被拒绝

    • 检查MCP服务器是否正在运行
    • 验证端口配置
    • 检查防火墙设置

  2. 扩展程序无法连接

    • 在扩展中验证 WebSocket URL
    • 检查Chrome扩展程序的权限
    • 监控扩展控制台日志

  3. Cloudflare 检测

    • 启用隐身模式
    • 检查指纹随机化
    • 验证类人行为

  4. 命令超时

    • 增加超时值
    • 检查网络连接
    • 验证扩展已连接

调试模式

# Enable debug logging
LOG_LEVEL=debug npm run dev

🤝 贡献

  1. 为仓库创建分支（或“克隆仓库”）
  2. 创建一个特性分支
  3. 进行你的更改
  4. 添加测试
  5. 运行代码检查和测试
  6. 提交拉取请求

📄 许可证

此项目遵循MIT许可协议，详情请参阅LICENSE文件。

🙏 致谢

  • MCP（模型上下文协议）规范
  • Chrome扩展API
  • WebSocket协议
  • 绕过Cloudflare的技术

📞 支持

对于问题和疑问：

  • 查看故障排除部分
  • 查看各个README文件
  • 在项目仓库中打开一个问题（或提交一个问题）
  • 查阅Chrome扩展程序的文档

注这个项目是为合法的自动化目的而设计的。请确保在使用此工具时遵守网站的服务条款及适用法律法规。

相关 MCP