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 / 小红书
功能范围
| MCP 工具 | 用途 |
|---|---|
bb_browser_status |
检查程序、适配器与浏览器连接状态，不代表账号已登录或搜索成功 |
search_x |
搜索 X 帖子 |
search_xiaohongshu |
搜索小红书笔记 |
read_xiaohongshu_note |
读取小红书笔记 |
read_xiaohongshu_comments |
读取小红书评论 |
仅开放这 5 个工具。没有发布、点赞、发评论、通用点击或任意 adapter 执行工具。只读指不主动修改网站业务数据；搜索仍可能导航或打开浏览器标签页。
当前验证情况
| 检查 | 结果 |
|---|---|
| Windows / Python 3.14 / MCP SDK 2.1.1 | 已运行协议测试 |
MCP initialize 握手 |
通过 |
tools/list 发现 5 个工具 |
通过 |
空搜索关键词返回 INVALID_ARGUMENT |
通过 |
| Windows 搜索参数不经过 shell 解释 | 在独立服务环境中验证过 |
| 小红书真实搜索 | 未成功，最近返回 Daemon request timed out |
| X 搜索、笔记和评论的真实返回 | 本发布包未完成端到端验证 |
| macOS / Linux | 未测试 |
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 启动命令、参数与环境变量。客户端负责启动服务进程，无需另开一个终端长期运行它。多个客户端通常各自启动一份服务进程，但仍可能共用同一个浏览器。
环境变量
| 变量 | 含义 |
|---|---|
BB_BROWSER_NODE |
Node 可执行文件，默认在 PATH 中查找 |
BB_BROWSER_CLI |
bb-browser 的 dist/cli.js 绝对路径；未设置时尝试 Windows 默认全局 npm 目录 |
BB_BROWSER_CDP_URL |
可选的浏览器调试地址；空值由 bb-browser 自行选择 |
BB_BROWSER_MIN_INTERVAL_S |
当前服务进程内两次 site 调用的最小间隔，默认 0.8 秒 |
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 是外部安装的依赖，分别遵循各自的许可证。