内容
# 本地浏览器 MCP 服务器
MCP（模型上下文协议）服务器，利用 Puppeteer 提供浏览器自动化功能，并结合 Google Gemini 2.0 Flash 进行 AI 图像生成。该服务器允许您控制本地 Chrome 浏览器实例，截取屏幕截图，进行点击和输入等交互操作，并生成自定义图像 - 非常适合测试网站和使用 Cursor 创建内容。
## 功能
- 🌐 **浏览器导航**：导航到 URL，返回/前进，刷新页面
- 📸 **屏幕截图**：捕获整个页面，视口或特定元素的屏幕截图
- 🖱️ **点击操作**：使用 CSS 选择器点击元素
- ⌨️ **文本输入**：在输入字段和表单中输入文本
- 📜 **滚动**：在任意方向滚动页面
- ⏳ **等待操作**：等待元素出现
- 📊 **页面信息**：获取当前页面标题，URL 和视口信息
- 🎨 **AI 图像生成**：使用 Google Gemini 2.0 Flash Preview 生成自定义图像
## 安装
1. **克隆/下载** 此存储库到您的本地机器
2. **安装依赖项**：
```bash
npm install
```
3. **构建项目**：
```bash
npm run build
```
4. **设置环境变量** （用于图像生成）：
在项目根目录中创建一个 `.env` 文件：
```bash
GOOGLE_AI_KEY=您的_google_ai_api_key_在此处
```
从 [Google AI Studio](https://makersuite.google.com/app/apikey) 获取您的 API 密钥。
## 与 Cursor 一起使用
### 步骤 1：启动 HTTP 服务器
使用 HTTP 模式是推荐的使用此 MCP 服务器的方式，以避免 ES 模块兼容性问题：
```bash
npm run start:http
```
这将服务器启动在 `http://localhost:3045` 上并保持运行。
### 步骤 2：在 Cursor 中配置 MCP
使用以下配置创建或更新您的 `cursor-mcp-config.json` 文件：
```json
{
"mcpServers": {
"local-browser": {
"command": "node",
"args": ["/绝对路径/到/您的/项目/mcp-http-bridge.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
**重要提示**：
- 将 `/绝对路径/到/您的/项目/` 替换为您的项目目录的实际绝对路径
- HTTP 桥（`mcp-http-bridge.js`）将 MCP 请求路由到 HTTP 服务器
- 使用 Cursor 中的工具之前，请确保 HTTP 服务器正在运行
### 步骤 3：重启 Cursor
更新配置后，重启 Cursor 以加载新的 MCP 服务器。
### 步骤 4：开始使用工具
配置完成后，您可以在 Cursor 中使用以下工具：
#### 浏览器导航
- `navigate_to_url` - 导航到任何 URL
- `go_back` - 在浏览器历史记录中返回
- `go_forward` - 在浏览器历史记录中前进
- `refresh_page` - 刷新当前页面
#### 屏幕截图和视觉捕捉
- `take_screenshot` - 捕获屏幕截图（整个页面，视口或特定元素）
#### 页面交互
- `click_element` - 使用 CSS 选择器点击元素
- `type_text` - 在输入字段中输入文本
- `scroll_page` - 在任意方向滚动页面
- `wait_for_element` - 等待元素出现
#### 页面信息
- `get_page_info` - 获取当前页面标题，URL 和视口信息
#### AI 图像生成
- `generate_image` - 使用 Google Gemini 2.0 Flash Preview 生成自定义图像
## 快速入门示例
以下是快速入门的方法：
1. **启动 HTTP 服务器**：
```bash
npm run start:http
```
2. **在 Cursor 中尝试这些命令**：
- "导航到 google.com 并截取屏幕截图"
- "生成山脉上的日落图像"
- "点击搜索按钮并输入 'hello world'"
## 示例工作流程
以下是测试您创建的网站时的典型工作流程：
1. **导航到本地开发服务器**：
```
使用 navigate_to_url 和 "http://localhost:3000"
```
2. **截取屏幕截图以查看当前状态**：
```
使用 take_screenshot 捕获整个页面
```
3. **与您的网站交互**：
```
使用 click_element 点击按钮
使用 type_text 填写表单
使用 scroll_page 测试滚动行为
```
4. **捕获结果**：
```
再次使用 take_screenshot 查看更改
```
## 工具参考
### navigate_to_url
将浏览器导航到特定 URL。
- `url` （必填）：要导航到的 URL
### take_screenshot
截取当前页面的屏幕截图。
- `fullPage` （可选）：捕获整个页面与仅视口
- `selector` （可选）：用于截取特定元素屏幕截图的 CSS 选择器
### click_element
点击由 CSS 选择器指定的元素。
- `selector` （必填）：要点击的元素的 CSS 选择器
- `waitFor` （可选）：点击后等待（默认值：1000）
### type_text
在输入字段中输入文本。
- `selector` （必填）：输入元素的 CSS 选择器
- `text` （必填）：要输入的文本
- `clear` （可选）：输入前清除字段（默认值：true）
### wait_for_element
等待页面上出现元素。
- `selector` （必填）：要等待的 CSS 选择器
- `timeout` （可选）：超时时间（毫秒）（默认值：5000）
### scroll_page
滚动页面。
- `direction` （必填）：'up'，'down'，'top' 或 'bottom'
- `amount` （可选）：向上/向下滚动的像素（默认值：500）
### get_page_info
获取当前页面的信息（标题，URL，视口大小）。
### refresh_page
刷新当前页面。
### go_back
在浏览器历史记录中返回。
### go_forward
在浏览器历史记录中前进。
### generate_image
使用 Google Gemini 2.0 Flash Preview 生成自定义 AI 图像。
- `description` （必填）：要生成的图像的文本描述
生成的图像会自动保存到 `generated-images/` 目录中，可以通过 `http://localhost:3045/download/{filename}` 中的 HTTP 下载。
## 开发
- **构建**：`npm run build`
- **开发模式**：`npm run dev` （监视更改）
- **启动**：`npm start` （可见浏览器）或 `npm run start:headless` （后台）
- **HTTP 测试服务器**：`npm run start:http` （可见）或 `npm run start:http:headless` （后台）
## 浏览器行为
- **可见模式**：浏览器窗口打开，您可以看到发生了什么
- **无头模式**：浏览器在后台运行（设置 `MCP_HEADLESS=true`）
- **独立配置文件**：使用 `/tmp/chrome-mcp-data` 以避免与您的主 Chrome 浏览器冲突
- **默认视口**：1280x720 像素
- **屏幕截图**：返回 base64 编码的 PNG 图像
## 故障排除
### 浏览器未启动
- 确保您的系统上已安装 Chrome 浏览器
- 检查是否有其他进程阻止 Chrome 浏览器启动
- 尝试重启 HTTP 服务器：`npm run start:http`
- 清除 Chrome 数据目录：`rm -rf /private/tmp/chrome-mcp-data`
### 元素未找到
- 验证 CSS 选择器是否正确
- 使用浏览器开发工具测试选择器
- 尝试使用 `wait_for_element` 等待元素加载
### Cursor 中不可用的 MCP 工具
- 确保 HTTP 服务器正在运行：`npm run start:http`
- 检查 `cursor-mcp-config.json` 是否具有正确的绝对路径
- 配置更改后重启 Cursor
- 验证 HTTP 桥文件是否存在：`mcp-http-bridge.js`
### 图像生成无法正常工作
- 确保在您的 `.env` 文件中设置了 `GOOGLE_AI_KEY`
- 从 [Google AI Studio](https://makersuite.google.com/app/apikey) 获取您的 API 密钥
- 检查 HTTP 服务器是否正在运行（图像生成需要 HTTP 模式）
### 权限问题
- 确保 MCP 服务器具有启动 Chrome 的权限
- 检查编译后的 JavaScript 文件的文件权限
- 在 macOS 上，您可能需要在系统偏好设置 > 安全性和隐私中允许 Chrome
## 安全注意事项
- 此服务器启动具有完全系统访问权限的真实浏览器
- 仅与受信任的网站和内容一起使用
- 浏览器在禁用某些安全功能的情况下运行以进行自动化
- 始终在受控环境中运行
## License
MIT License - see LICENSE file for details.
