web-search-server

面向 AI 的本地 Web 搜索 MCP 服务：多引擎聚合搜索、网页抓取回退链、站点定向搜索。

• 传输：stdio（在 MCP 客户端里注册本地 MCP）；默认端口 8011（HTTP 模式时）

• 运行：python server.py（依赖见 requirements.txt；可选依赖缺失会自动降级）

• 测试：python -m pytest tests/ -q（全部为 mock 测试，不依赖网络）

工具清单（18）

Related MCP server: Web Search MCP Server

站点定向搜索

直接调各平台 API / 复用浏览器会话取结构化结果，比通用网页搜索准确（GitHub 走公开 REST API，无需任何凭据）。

Twitter(X) 接入（twitter_search）

X 没有免费公开搜索 API，未登录访问 x.com 是空白页（2026-10-04 实测）； 公共 Nitter 镜像当天也全部不可用（Cloudflare / Anubis / 429）。所以读 X 必须借登录态， 三条通路按推荐顺序：

① 遇到反爬/登录墙，回退用 Playwright MCP 驱动已登录的浏览器（零配置，推荐）

本项目的回退原则：本地抓取/渲染过不去（反爬、登录墙）时，最终回退是交给 Playwright MCP（mcp__playwright__*，browser_ 工具）在用户已登录的浏览器里打开页面完成任务* —— 不自己造浏览器、不要密码。做法：让 Playwright MCP 以 --browser msedge --executable-path <系统 Edge> --extension 的扩展模式桥接你自己的浏览器， X 登录态就在里面（2026-10-04 实测：x.com 搜索页可直接抽到实时推文）。读 X 时： browser_tabs(action="new", url=...) 开新标签页（别动扩展 connect 页），再用 browser_evaluate 抽取 article[data-testid="tweet"]。

② cookie 会话（静默，本工具自带）

不需弹浏览器时用这条路：

1. 在已登录 x.com 的浏览器（如 Edge）里：F12 → Application → Cookies → https://x.com

2. 复制 auth_token 与 ct0 两个值

3. 配到 MCP 客户端的 env（如 ZCode：%USERPROFILE%\.zcode\cli\config.json → mcp.servers.web-search-server.env）：

"env": {
  "X_AUTH_TOKEN": "<auth_token 的值>",
  "X_CT0": "<ct0 的值>"
}

4. 重启 MCP 客户端后生效。cookie 等同于账号凭据：只放本机 env，不要写进仓库、 笔记、聊天记录或记忆文件（本仓库代码也不会打印/落盘它们）。

   • 登录态过期时工具会提示「cookie 无效或已过期」，重新复制即可。

③ 调试端口浏览器（进阶，本工具自带）

Edge/Chrome ≥136 禁止用默认配置目录开 --remote-debugging-port（实测 Edge 154 拒绝），且实测把 Edge 默认配置复制到独立目录启动后 X 仍是未登录。所以这条路需要：

# 用独立配置目录启动（首次在该窗口里登录一次 X，之后登录态常驻）
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --user-data-dir="<独立目录>\edge-agent-profile" --remote-debugging-port=9222

保持该实例运行，本工具的浏览器后端会新开标签页搜索、抽取后关闭（用户可见）。 Chrome 以调试端口启动期间不要用它登录敏感账号（调试端口对本机程序开放）。

用法

twitter_search("audio llm")                 # 最新推文
twitter_search("audio llm", mode="top")     # 热门
twitter_search("from:elonmusk grok")        # 读某人推文（X 搜索语法通用）
twitter_search("@elonmusk grok")            # 提及

返回：@handle、时间、正文、互动数（回复/转推/喜欢/查看）、推文链接。

实现说明（改版自愈）

主要环境变量