MCP Browser Text Reader

一个强大的 Model Context Protocol (MCP) 服务器，用于控制真实的Chrome浏览器并读取页面文字内容。支持多种文本提取方式和灵活的配置选项。

功能特性

• 🌐 真实Chrome浏览器控制: 直接控制系统中的Chrome浏览器，可见窗口操作
• 📝 灵活的文本提取: 支持可见文本、所有文本、innerText、textContent等多种提取方式
• 🎯 精确元素选择: 使用CSS选择器精确定位需要提取的元素
• ⏱️ 智能等待机制: 支持等待特定元素加载完成
• 🔍 详细的元数据: 提供字符数、词数、提取时间等详细信息
• 🛡️ 错误处理: 完善的错误处理和资源清理机制
• 🔄 智能连接: 自动连接现有Chrome实例或启动新实例
• 👀 可视化操作: 实时观察浏览器操作过程

安装

1. 克隆项目

git clone <repository-url>
cd mcp-browser-text-reader

2. 安装依赖

npm install

3. 确保Chrome浏览器已安装

确保系统中已安装Google Chrome浏览器：

• macOS: /Applications/Google Chrome.app/
• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe
• Linux: /usr/bin/google-chrome

4. 编译 TypeScript

npm run build

使用方法

作为 MCP 服务器运行

npm start

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加以下配置：

位置: .cursor/mcp.json

{
  "mcpServers": {
    "browser-text-reader": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"]
    }
  }
}

在 Claude Desktop 中配置

位置: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "browser-text-reader": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"]
    }
  }
}

可用工具

1. get_page_text

获取指定URL页面的文本内容

参数:

• url (可选): 要读取的网页URL
• selector (可选): CSS选择器，用于选择特定元素
• waitForSelector (可选): 等待特定元素出现的CSS选择器
• timeout (可选): 超时时间（毫秒），默认10000
• includeHidden (可选): 是否包含隐藏元素，默认false
• textType (可选): 文本提取类型，可选值：visible、all、innerText、textContent

示例:

{
  "url": "https://example.com",
  "selector": "article",
  "textType": "visible",
  "timeout": 15000
}

2. get_current_page_text

获取当前浏览器页面的文本内容

参数:

• selector (可选): CSS选择器
• includeHidden (可选): 是否包含隐藏元素
• textType (可选): 文本提取类型

3. navigate_to_page

导航到指定URL

参数:

• url (必需): 要导航到的网页URL
• waitForSelector (可选): 等待特定元素出现
• timeout (可选): 超时时间

4. get_page_info

获取当前页面的基本信息（标题、URL等）

5. launch_chrome_manually

手动启动Chrome浏览器（可见窗口）

6. get_browser_status

获取浏览器连接状态

7. close_browser

关闭浏览器实例或断开连接

文本提取类型说明

• visible (默认): 只提取用户可见的文本
• all: 提取所有文本内容，包括隐藏元素
• innerText: 使用 element.innerText 提取文本
• textContent: 使用 element.textContent 提取文本

使用示例

在 AI 助手中使用

1. 读取网页内容:

   请使用 get_page_text 工具读取 https://news.ycombinator.com 的内容
   

2. 提取特定元素:

   请读取当前页面中所有 h2 标题的文本
   

3. 等待动态内容加载:

   请访问 https://example.com 并等待 .content 元素加载完成后提取文本
   

直接测试

运行测试脚本来验证功能：

npm run build
# 运行Chrome浏览器测试
node dist/test-chrome-server.js

测试将会：

1. 启动可见的Chrome浏览器窗口
2. 导航到测试网页
3. 提取页面文本内容
4. 演示各种功能

开发

项目结构

src/
├── index.ts                # MCP 服务器主入口
├── chrome-browser-manager.ts # Chrome浏览器管理器
└── test-chrome-server.ts   # Chrome测试脚本

dist/                       # 编译后的 JavaScript 文件
package.json               # 项目配置
tsconfig.json             # TypeScript 配置

开发模式

# 监听文件变化并自动重新编译
npm run dev

构建

npm run build

故障排除

常见问题

1. Chrome浏览器未安装或路径错误 确保系统已安装Chrome浏览器，并且路径正确。

2. 权限问题 确保有足够的权限运行浏览器，在某些环境中可能需要额外的参数。

3. 超时错误 增加 timeout 参数值，特别是对于加载较慢的页面。

4. 内存使用过高 定期调用 close_browser 工具来释放资源。

调试

启用详细日志输出：

DEBUG=* npm start

技术栈

• Node.js: JavaScript 运行时
• TypeScript: 类型安全的 JavaScript
• Puppeteer: Chrome浏览器自动化
• MCP SDK: Model Context Protocol 官方 SDK
• Zod: 运行时类型验证

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.0

• 初始版本
• 支持基本的页面文本提取功能
• 支持多种文本提取类型
• 完整的 MCP 协议支持