浏览器控制器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
快速入门
- 克隆仓库
git clone
cd browser-controller-mcp- 设置MCP服务器
cd browser-mcp-server
npm install
npm run build
npm start- 加载Chrome扩展程序
- 打开Chrome浏览器并导航至 chrome://extensions/ - 启用“开发者模式” - 点击“加载未打包扩展”并选择 browser-extension 文件夹
- 配置光标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连接
- 输入验证和清理
🐛 故障排除
常见问题
- 连接被拒绝
- 检查MCP服务器是否正在运行 - 验证端口配置 - 检查防火墙设置
- 扩展程序无法连接
- 在扩展中验证 WebSocket URL - 检查Chrome扩展程序的权限 - 监控扩展控制台日志
- Cloudflare 检测
- 启用隐身模式 - 检查指纹随机化 - 验证类人行为
- 命令超时
- 增加超时值 - 检查网络连接 - 验证扩展已连接
调试模式
# Enable debug logging
LOG_LEVEL=debug npm run dev🤝 贡献
- 为仓库创建分支（或“克隆仓库”）
- 创建一个特性分支
- 进行你的更改
- 添加测试
- 运行代码检查和测试
- 提交拉取请求
📄 许可证
此项目遵循MIT许可协议，详情请参阅LICENSE文件。
🙏 致谢
- MCP（模型上下文协议）规范
- Chrome扩展API
- WebSocket协议
- 绕过Cloudflare的技术
📞 支持
对于问题和疑问：
- 查看故障排除部分
- 查看各个README文件
- 在项目仓库中打开一个问题（或提交一个问题）
- 查阅Chrome扩展程序的文档
______________________________________________________________________
注这个项目是为合法的自动化目的而设计的。请确保在使用此工具时遵守网站的服务条款及适用法律法规。