bb-browser-readonly-mcp

一个独立的、实验性的 MCP Server，把本机 bb-browser CLI 的部分只读能力提供给 Codex 等 MCP 客户端。无需其他智能体项目或其 Python 环境。

目前只验证了 Windows 下的 MCP 协议接入，尚未验证真实搜帖成功。 最近的小红书搜索测试返回 Daemon request timed out。请把本项目视为可复用的封装起点，不要把工具注册成功等同于网站检索可用。

本项目是社区封装，与 bb-browser 官方无隶属关系；它不是原官方 MCP 的完整替代品，也不会恢复 CLI 的 --mcp 参数。

Codex / 其他 MCP 客户端
    ↓ MCP stdio
本项目 server.py → backend.py
    ↓ 执行命令
本机 bb-browser CLI
    ↓
Chrome → X / 小红书

功能范围

仅开放这 5 个工具。没有发布、点赞、发评论、通用点击或任意 adapter 执行工具。只读指不主动修改网站业务数据；搜索仍可能导航或打开浏览器标签页。

Related MCP server: SocialDataX 小红书 Xiaohongshu XHS RedNote MCP

当前验证情况

bb-browser、浏览器登录状态及网站 adapter 是独立的运行条件。本项目不能保证它们始终可用。

安装

依赖：Python 3.10+、Node.js 18+、npm，以及 bb-browser 支持的浏览器。最低版本来自依赖包要求，实际协议测试环境是 Python 3.14；其他 Python 版本尚未测试。

下载本仓库到一个固定目录，在该目录打开 PowerShell：

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm install -g bb-browser@0.14.2
bb-browser site update

requirements.txt 固定 MCP SDK 版本。requirements.lock.txt 是 Windows / Python 3.14 测试环境的完整版本快照，包含 Windows 专用依赖；不要把它当作跨平台锁文件。

bb-browser 需要在其实际使用的浏览器配置中完成网站登录。本项目不提供账号，不复制 Cookie，也不读取其他项目的 .env。如果 BB_BROWSER_CDP_URL 为空，浏览器选择遵循 bb-browser 自己的行为。

接入 Codex

将下面内容加入 Codex 的 config.toml。先把所有 C:/path/to/... 替换为你自己电脑上的绝对路径。 Python 必须指向刚创建的虚拟环境。

[mcp_servers.bb-browser-readonly]
enabled = true
command = "C:/path/to/bb-browser-readonly-mcp/.venv/Scripts/python.exe"
args = ["-E", "-s", "C:/path/to/bb-browser-readonly-mcp/server.py"]
cwd = "C:/path/to/bb-browser-readonly-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120
enabled_tools = ["bb_browser_status", "search_x", "search_xiaohongshu", "read_xiaohongshu_note", "read_xiaohongshu_comments"]

[mcp_servers.bb-browser-readonly.env]
BB_BROWSER_NODE = "C:/path/to/node.exe"
BB_BROWSER_CLI = "C:/path/to/npm/node_modules/bb-browser/dist/cli.js"
BB_BROWSER_CDP_URL = ""

定位 Windows 安装路径：

(Get-Command node).Source
npm root -g

把 npm root -g 输出的目录与 /bb-browser/dist/cli.js 拼成 BB_BROWSER_CLI。本服务直接运行 Node 和 CLI 脚本，不经 .cmd 或 shell 转义搜索词。

其他支持 stdio 的 MCP 客户端也可以使用相同的 Python 启动命令、参数与环境变量。客户端负责启动服务进程，无需另开一个终端长期运行它。多个客户端通常各自启动一份服务进程，但仍可能共用同一个浏览器。

环境变量

macOS / Linux 用户需要自行设置 BB_BROWSER_CLI，并改用 .venv/bin/python 等对应路径。相关平台尚未测试，不能据此声称兼容。

不操作浏览器的协议测试

.\.venv\Scripts\python.exe smoke.py

smoke.py 使用自己的 Python 解释器启动同目录 server.py，只进行 MCP 握手、工具发现和空关键词错误检查。它不会调用状态工具或实际搜索，也不要求已安装 bb-browser 或已登录浏览器。

成功时输出包含：

{"handshake":"OK","tool_count":5,"empty_keyword":"INVALID_ARGUMENT","browser_operations_performed":false}

协议测试通过后，仍需单独验证实际网站调用。如果工具返回 LOGIN_REQUIRED，在所选浏览器中完成登录后重试；如果返回 Daemon request timed out，应继续检查 bb-browser 守护进程和浏览器连接，不能据此宣称搜帖可用。

文件

• server.py：MCP 工具注册与 stdio 服务入口。

• backend.py：参数处理、CLI 执行与结果解析。

• smoke.py：不操作浏览器的 MCP 协议测试。

• requirements.txt / requirements.lock.txt：直接依赖与测试环境快照。

源码不包含浏览器配置、Cookie、账号或虚拟环境。

许可证

本项目采用 MIT License。bb-browser 和 MCP SDK 是外部安装的依赖，分别遵循各自的许可证。