Skip to content
Back to search

cn-scraper-mcp

Let AI agents search the Chinese internet via MCP — Taobao, JD, Xiaohongshu, Zhihu, Weibo, Bilibili, ZSXQ, Douban, Dianping, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/goesbyhc--cn-scraper-mcp/badge.svg)](/listings/goesbyhc--cn-scraper-mcp)

HTML

<a href="/listings/goesbyhc--cn-scraper-mcp"><img src="/api/listings/goesbyhc--cn-scraper-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install cn-scraper-mcp

也可以从源码安装开发版本:

git clone https://github.com/goesByhc/cn-scraper-mcp.git
cd cn-scraper-mcp
pip install .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 339 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/goesByhc/cn-scraper-mcp/master/assets/cn-scraper-mcp-icon.png" alt="CN Scraper MCP 图标" width="220">
  3. </p>
  4. <h1 align="center">CN Scraper MCP</h1>
  5. <p align="center">
  6. <strong>让 AI Agent 直接搜索中国互联网——淘宝、京东、小红书、知乎、微博、B站、知识星球……不再被反爬墙挡住。</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a>
  10. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible"></a>
  11. <a href="https://github.com/goesByhc/cn-scraper-mcp/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
  12. <a href="https://github.com/goesByhc/cn-scraper-mcp/actions/workflows/ci.yml"><img src="https://github.com/goesByhc/cn-scraper-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  13. </p>
  14. <!-- mcp-name: io.github.goesByhc/cn-scraper-mcp -->
  15. ---
  16. ## 这是什么
  17. 每个 AI Agent(Codex、Claude Code、Cursor、Trae)都能搜网页,但中文平台通常需要登录态、浏览器环境或平台专用参数:
  18. - **淘宝**:需要浏览器一致的网络指纹和登录 Cookie
  19. - **京东**:依赖已登录的本地浏览器环境
  20. - **小红书**:需要住宅 IP、本地浏览器和搜索结果中的访问参数
  21. - **知乎**:游客搜索已关闭,全部 API 需要登录态
  22. - **拼多多**:平台限制严格,目前不推荐使用
  23. - **微博**:搜索 API 需要登录态(SUB token),热搜游客即可访问
  24. - **抖音**:需要浏览器登录并可能人工处理验证码
  25. - **B站**:搜索、热门、视频详情和评论可直接使用公开 API
  26. - **豆瓣**:条目搜索、条目详情和短评/影评
  27. - **大众点评**:商户搜索、商户详情和用户评价
  28. - **知识星球**:付费社群,内容藏在 cookie 认证的 REST API 后面
  29. **这个项目就是把踩了好几个月的坑打包成一个 MCP Server**——你的 Agent 一句话就能搜:`taobao_search("儿童学习桌")`。
  30. ### 安全与隐私
  31. `cn-scraper-mcp` 在你的电脑上本地运行,不需要把 Cookie、账号密码或浏览器 Profile 上传到任何中转服务器:
  32. - Cookie 默认保存在 `~/.cn-scraper-cookies/`,京东登录态保存在本地 Chrome Profile。
  33. - 登录过程直接发生在平台官方页面,软件不会读取或保存你的账号密码。
  34. - Cookie 值不会写入日志,也不会通过 MCP 工具结果返回给 Agent;工具只返回状态、字段名和本地路径等非敏感信息。
  35. - 发起抓取或在线登录验证时,凭证只会发送给对应平台域名。
  36. - 代码完全开源,所有凭证处理流程都可以审查。
  37. 建议仍像保护浏览器登录态一样保护本机账号:不要分享 Cookie 文件,不要把凭证提交到 Git,并限制本地文件的访问权限。
  38. ---
  39. ## 平台支持
  40. ### 电商
  41. | 平台 | 方式 | 无需浏览器 | 限制 | 稳定性 |
  42. |------|------|-----------|------|--------|
  43. | **淘宝/Tmall** | `curl_cffi` + MTOP 签名 | ✅ | 宽松¹ | ✅ 稳定 |
  44. | **京东/JD** | Chrome CDP headful | 需 Chrome | 中等 | ✅ 稳定² |
  45. | **拼多多/PDD** | Chrome CDP + iPhone UA | 需 Chrome | 单次搜索限制³ | ⚠️ 不推荐 |
  46. > ¹ 淘宝无硬性限流,但平台可能随时收紧,不建议高频批量抓取。
  47. > ² 京东由本地 Chrome 生成登录态和动态签名,工具读取结构化 API 响应;通过 `guided_login("jd")` 可自动初始化持久化 Profile。
  48. > ³ 拼多多每个浏览器会话仅放行第一次搜索,之后永久"系统繁忙"。单次搜索结果零实用价值,引擎代码保留但不推荐使用。
  49. ### 内容社区
  50. | 平台 | 方式 | 无需浏览器 | 限制 | 稳定性 |
  51. |------|------|-----------|------|--------|
  52. | **小红书/XHS** | 本地 Chrome CDP + cookie | 需 Chrome | 中等⁴ | ✅ 稳定 |
  53. | **知乎/Zhihu** | REST API v4 | ✅ | 正常 | ✅ 稳定 |
  54. | **知识星球/ZSXQ** | REST API v2 | ✅ | 正常 | ✅ 稳定 |
  55. | **微博/Weibo** | REST API | ✅ | 正常 | ✅ 稳定 |
  56. | **抖音/Douyin** ⚠️ | Chrome CDP + 验证码轮询 | 需 Chrome | 实验性⁵ | ⚠️ 实验性 |
  57. | **B站/Bilibili** | 公开 Web API | ✅ | 建议低频调用 | ✅ 稳定 |
  58. | **豆瓣/Douban** | 移动端 JSON API | ✅ | 搜索可能触发风控 | ⚠️ 依会话 |
  59. | **大众点评/Dianping** | 公开网页解析 | ✅ | 可能触发页面风控 | ⚠️ 依页面结构 |
  60. > ⁴ 小红书只允许住宅 IP——云浏览器/数据中心 IP 直接封。必须用本地 Chrome。
  61. > ⁵ 抖音搜索需要登录态 + 手动过滑块验证码。支持 120s 等待用户手动验证,通过后自动抓取。`guided_login("douyin")` 可引导登录。
  62. ## 快速开始
  63. ### 安装
  64. ```bash
  65. pip install cn-scraper-mcp
  66. ```
  67. 也可以从源码安装开发版本:
  68. ```bash
  69. git clone https://github.com/goesByhc/cn-scraper-mcp.git
  70. cd cn-scraper-mcp
  71. pip install .
  72. ```
  73. ### 推荐:CDP 自动登录并保存 Cookie
  74. 安装并连接 MCP 后,直接让 Agent 调用:
  75. ```text
  76. guided_login(platform="weibo")
  77. ```
  78. 它会打开本地 Chrome 并进入平台官方登录页。你自己扫码或输入密码后,工具通过 CDP 自动读取完整 Cookie(包括 JavaScript 无法读取的 HttpOnly Cookie),再保存到本机 `~/.cn-scraper-cookies/`。京东则保存到本地持久化 Chrome Profile。
  79. 这是推荐方式,因为它不会要求你复制 Cookie,不容易漏掉关键字段,也更适合 Cookie 过期后的重新登录。可用平台名包括 `taobao`、`jd`、`xiaohongshu`、`zhihu`、`weibo`、`zsxq`、`douyin`、`pdd`、`douban` 和 `dianping`。
  80. 已有通过远程调试端口启动且登录完成的 Chrome 时,也可以调用:
  81. ```text
  82. harvest_cookies(platform="weibo")
  83. ```
  84. ### 启动
  85. ```bash
  86. cn-scraper-mcp
  87. # 或: python -m cn_scraper_mcp.server
  88. ```
  89. ### Docker
  90. 容器内预装 Chromium,无需本地浏览器:
  91. ```bash
  92. docker build -t cn-scraper-mcp .
  93. docker run -i --rm \
  94. -v ~/.cn-scraper-cookies:/root/.cn-scraper-cookies \
  95. -v ~/.jd_login_profile:/root/.jd_login_profile \
  96. cn-scraper-mcp
  97. ```
  98. 远程服务器部署可以切换到 HTTP transport,通过 `IP + 端口` 连接:
  99. ```bash
  100. docker pull ghcr.io/goesbyhc/cn-scraper-mcp:latest
  101. docker run -d --name cn-scraper-mcp \
  102. -p 8000:8000 \
  103. -e CN_SCRAPER_TRANSPORT=http \
  104. -e CN_SCRAPER_HOST=0.0.0.0 \
  105. -e CN_SCRAPER_PORT=8000 \
  106. -e CN_SCRAPER_PATH=/mcp \
  107. -v ~/.cn-scraper-cookies:/root/.cn-scraper-cookies \
  108. -v ~/.jd_login_profile:/root/.jd_login_profile \
  109. ghcr.io/goesbyhc/cn-scraper-mcp:latest
  110. ```
  111. 远程 MCP endpoint:
  112. ```text
  113. http://<server-ip>:8000/mcp
  114. ```
  115. 也可以使用 Docker Compose:
  116. ```bash
  117. docker compose --profile remote up -d cn-scraper-http
  118. ```
  119. 可用环境变量:
  120. | 变量 | 默认值 | 说明 |
  121. |------|------|------|
  122. | `CN_SCRAPER_TRANSPORT` | `stdio` | `stdio`、`http`、`sse`,也接受 `streamable-http` 作为 `http` 别名 |
  123. | `CN_SCRAPER_HOST` | `0.0.0.0` | HTTP/SSE 模式监听地址 |
  124. | `CN_SCRAPER_PORT` | `8000` | HTTP/SSE 模式监听端口 |
  125. | `CN_SCRAPER_PATH` | `/mcp` | HTTP/SSE MCP endpoint 路径 |
  126. > 远程 HTTP 模式会让 MCP 工具通过网络访问本机 Cookie/Profile 目录,请勿直接裸露公网端口。建议放在内网、VPN、防火墙白名单或带鉴权的反向代理后面。小红书、京东、抖音等依赖本地浏览器、住宅 IP 或人工验证码的平台,在远程服务器上的稳定性取决于服务器网络与图形环境。
  127. 当平台要求人工处理登录、验证码或风控页时,工具会返回统一的 `ACTION_REQUIRED` 结构,并在 `action_required` 字段中说明平台、原因、处理动作、处理链接和建议重试的工具。当前抖音验证码已接入该结构;远程 Docker 场景下仍需要你通过可见浏览器或后续 noVNC 网页完成验证。
  128. Agent 集成配置:
  129. ```toml
  130. # Codex ~/.codex/config.toml
  131. [mcp_servers.cn-scraper]
  132. command = "docker"
  133. args = ["run", "-i", "--rm",
  134. "-v", "/本机绝对路径/.cn-scraper-cookies:/root/.cn-scraper-cookies",
  135. "-v", "/本机绝对路径/.jd_login_profile:/root/.jd_login_profile",
  136. "cn-scraper-mcp"]
  137. ```
  138. 请把 `/本机绝对路径/` 替换为真实路径;MCP 客户端直接启动进程时不会替你展开 `~`。
  139. > Docker 镜像内置 Chromium + `--no-sandbox`。京东 headful 模式如需 Xvfb,设置环境变量 `XVFB_WRAPPER=1`。小红书仍需住宅 IP——数据中心 IP 会被封。
  140. ---
  141. ## MCP 工具一览
  142. ### 电商搜索
  143. | 工具 | 说明 |
  144. |------|------|
  145. | `taobao_search` | 淘宝/天猫关键词搜索 → 价格、销量、店铺 |
  146. | `taobao_product` | 淘宝商品详情 → 标题、价格、店铺 |
  147. | `jd_search` | 京东关键词搜索 → SKU、价格、商品名 |
  148. | `jd_product` | 京东商品详情 → 名称、价格、店铺、规格 |
  149. | `pdd_search` | 拼多多搜索 → 仅首次有效 |
  150. | `pdd_product_detail` | 拼多多商品详情 → 不限次数 |
  151. ### 内容社区
  152. | 工具 | 说明 |
  153. |------|------|
  154. | `xiaohongshu_search` | 小红书笔记搜索 → 标题、作者、点赞、`noteId`、`xsec_token` |
  155. | `xiaohongshu_note` | 小红书笔记详情 → 标题、正文、作者、标签、互动数、发布时间 |
  156. | `xiaohongshu_comments` | 小红书笔记首屏评论 → 评论内容、用户、点赞、时间(需要 `noteId` + `xsec_token`) |
  157. | `zhihu_search` | 知乎搜索 → 问题、文章 |
  158. | `zhihu_hot_list` | 知乎热榜 |
  159. | `zhihu_comments` | 知乎回答评论(支持分页) |
  160. | `zhihu_answer` | 知乎回答完整正文 |
  161. | `zhihu_question_answers` | 知乎问题下的回答列表 |
  162. | `weibo_search` | 微博搜索 → 微博帖子内容 |
  163. | `weibo_hot_list` | 微博热搜榜 |
  164. | `weibo_user_timeline` | 微博用户时间线 |
  165. | `weibo_comments` | 微博帖子评论(支持分页) |
  166. | `weibo_post` | 微博帖子完整详情 |
  167. | `douyin_search` | 抖音搜索 → CDP 浏览器 + 验证码轮询(⚠️ 实验性) |
  168. | `douyin_hot_list` | 抖音热搜榜 |
  169. | `douyin_video` | 抖音视频详情 |
  170. | `douyin_comments` | 抖音视频评论 |
  171. | `bilibili_search` | B 站视频搜索(纯 HTTP,无需登录) |
  172. | `bilibili_popular` | B 站热门视频榜 |
  173. | `bilibili_video` | B 站视频详情及互动统计 |
  174. | `bilibili_comments` | B 站视频一级评论(支持分页) |
  175. | `douban_search` | 豆瓣书籍、电影、音乐等条目搜索 |
  176. | `douban_subject` | 豆瓣条目详情 |
  177. | `douban_reviews` | 豆瓣条目短评/影评 |
  178. | `dianping_search` | 大众点评商户搜索 |
  179. | `dianping_shop` | 大众点评商户详情 |
  180. | `dianping_reviews` | 大众点评商户评价 |
  181. | `zsxq_topics` | 知识星球付费社群帖子 |
  182. | `zsxq_article` | 知识星球文章全文 |
  183. ### Cookie 管理
  184. | 工具 | 说明 |
  185. |------|------|
  186. | `check_cookies` | 检查所有平台 Cookie 状态 |
  187. | `verify_login` | 在线验证知乎、微博、知识星球、抖音登录态;不支持的平台明确返回 unsupported |
  188. | `diagnose` | 环境诊断——依赖版本、浏览器、CDP 端口 |
  189. | `harvest_cookies` | CDP 自动收割 Cookie(包括 HttpOnly) |
  190. | `guided_login` | 引导登录——自动打开浏览器 → 你扫码 → 登录后自动收割 Cookie |
  191. ## MCP 客户端配置
  192. ### Codex
  193. `~/.codex/config.toml`:
  194. ```toml
  195. [mcp_servers.cn-scraper]
  196. command = "cn-scraper-mcp"
  197. args = []
  198. ```
  199. 保存后可用 `codex mcp list` 检查连接状态。
  200. ### Claude Code / Cursor / Reasonix
  201. 这三个客户端都支持标准的 `mcpServers` JSON:
  202. - Claude Code:项目根目录 `.mcp.json`
  203. - Cursor:全局 `~/.cursor/mcp.json`,或项目目录 `.cursor/mcp.json`
  204. - Reasonix:项目根目录 `.mcp.json`
  205. ```json
  206. {
  207. "mcpServers": {
  208. "cn-scraper": {
  209. "command": "cn-scraper-mcp",
  210. "args": []
  211. }
  212. }
  213. }
  214. ```
  215. ### Trae
  216. Trae 不同版本的配置文件位置可能不同。建议在设置中的 MCP 管理界面添加本地 stdio Server:名称填写 `cn-scraper`,命令填写 `cn-scraper-mcp`,参数留空。
  217. > 如果客户端提示找不到命令,先用 `where cn-scraper-mcp`(Windows)或 `which cn-scraper-mcp`(macOS/Linux)找到完整路径,再把 `command` 替换为该路径。
  218. ---
  219. ## 更多文档
  220. - [架构设计](https://github.com/goesByhc/cn-scraper-mcp/blob/master/docs/architecture.md):职责边界、平台契约和 Agent 开发守则
  221. - [开发规范](https://github.com/goesByhc/cn-scraper-mcp/blob/master/CONTRIBUTING.md):环境、编码、测试和 Review 要求
  222. ---
  223. ## 常见问题
  224. **Q: 使用这个软件安全吗?**
  225. 软件在你的电脑上本地运行,不经过项目方的中转服务器。Cookie 和浏览器 Profile 保存在本机,Cookie 值不会写入日志或通过 MCP 返回给 Agent;需要访问平台时,凭证只发送给对应的平台域名。
  226. **Q: 软件会读取或保存账号密码吗?**
  227. 不会。登录发生在平台官方页面,由你自己扫码或输入密码;工具只在登录完成后通过 CDP 保存浏览器产生的 Cookie。
  228. **Q: Cookie 保存在什么地方?**
  229. Cookie 默认保存在 `~/.cn-scraper-cookies/`,京东使用本地持久化 Chrome Profile。请像保护已登录浏览器一样保护这些文件,不要分享或提交到 Git。
  230. **Q: 怎么初始化 Cookie 最方便?**
  231. 用 `guided_login("平台名")` 工具。它会自动打开 Chrome → 导航到登录页 → 等你扫码/输密码 → 登录后自动收割 Cookie 并保存。
  232. **Q: 合法吗?**
  233. 仅用于**学习和研究目的**。批量抓取可能违反平台服务条款。风险自负。切勿用于垃圾信息、DDoS 或商业级大规模抓取。
  234. ---
  235. ## 许可证
  236. MIT — 详见 [LICENSE](https://github.com/goesByhc/cn-scraper-mcp/blob/master/LICENSE)。
  237. ## 支持项目
  238. 如果这个项目帮你节省了时间,可以请作者喝杯咖啡:
  239. <p align="center">
  240. <img src="assets/wechat-pay.jpg" alt="微信赞赏码" width="240">
  241. </p>
  242. ## 致谢
  243. - [curl_cffi](https://github.com/lexiforest/curl_cffi) — TLS 指纹伪装
  244. - [FastMCP](https://github.com/jlowin/fastmcp) — MCP Server 框架
  245. - [websockets](https://github.com/python-websockets/websockets) — 异步 WebSocket
  246. ---
  247. *Made with ☕ and months of frustration at Chinese platform anti-bot walls.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.