{ "markdown": "

\n \"CN\n

\n\n

CN Scraper MCP

\n\n

\n 让 AI Agent 直接搜索中国互联网——淘宝、京东、小红书、知乎、微博、B站、知识星球……不再被反爬墙挡住。\n

\n\n

\n \"Python\n \"MCP\n \"MIT\n \"CI\"\n

\n\n\n\n---\n\n## 这是什么\n\n每个 AI Agent（Codex、Claude Code、Cursor、Trae）都能搜网页，但中文平台通常需要登录态、浏览器环境或平台专用参数：\n\n- **淘宝**：需要浏览器一致的网络指纹和登录 Cookie\n- **京东**：依赖已登录的本地浏览器环境\n- **小红书**：需要住宅 IP、本地浏览器和搜索结果中的访问参数\n- **知乎**：游客搜索已关闭，全部 API 需要登录态\n- **拼多多**：平台限制严格，目前不推荐使用\n- **微博**：搜索 API 需要登录态（SUB token），热搜游客即可访问\n- **抖音**：需要浏览器登录并可能人工处理验证码\n- **B站**：搜索、热门、视频详情和评论可直接使用公开 API\n- **豆瓣**：条目搜索、条目详情和短评/影评\n- **大众点评**：商户搜索、商户详情和用户评价\n- **知识星球**：付费社群，内容藏在 cookie 认证的 REST API 后面\n\n**这个项目就是把踩了好几个月的坑打包成一个 MCP Server**——你的 Agent 一句话就能搜：`taobao_search(\"儿童学习桌\")`。\n\n### 安全与隐私\n\n`cn-scraper-mcp` 在你的电脑上本地运行，不需要把 Cookie、账号密码或浏览器 Profile 上传到任何中转服务器：\n\n- Cookie 默认保存在 `~/.cn-scraper-cookies/`，京东登录态保存在本地 Chrome Profile。\n- 登录过程直接发生在平台官方页面，软件不会读取或保存你的账号密码。\n- Cookie 值不会写入日志，也不会通过 MCP 工具结果返回给 Agent；工具只返回状态、字段名和本地路径等非敏感信息。\n- 发起抓取或在线登录验证时，凭证只会发送给对应平台域名。\n- 代码完全开源，所有凭证处理流程都可以审查。\n\n建议仍像保护浏览器登录态一样保护本机账号：不要分享 Cookie 文件，不要把凭证提交到 Git，并限制本地文件的访问权限。\n\n---\n\n## 平台支持\n\n### 电商\n\n| 平台 | 方式 | 无需浏览器 | 限制 | 稳定性 |\n|------|------|-----------|------|--------|\n| **淘宝/Tmall** | `curl_cffi` + MTOP 签名 | ✅ | 宽松¹ | ✅ 稳定 |\n| **京东/JD** | Chrome CDP headful | 需 Chrome | 中等 | ✅ 稳定² |\n| **拼多多/PDD** | Chrome CDP + iPhone UA | 需 Chrome | 单次搜索限制³ | ⚠️ 不推荐 |\n\n> ¹ 淘宝无硬性限流，但平台可能随时收紧，不建议高频批量抓取。\n> ² 京东由本地 Chrome 生成登录态和动态签名，工具读取结构化 API 响应；通过 `guided_login(\"jd\")` 可自动初始化持久化 Profile。\n> ³ 拼多多每个浏览器会话仅放行第一次搜索，之后永久\"系统繁忙\"。单次搜索结果零实用价值，引擎代码保留但不推荐使用。\n\n### 内容社区\n\n| 平台 | 方式 | 无需浏览器 | 限制 | 稳定性 |\n|------|------|-----------|------|--------|\n| **小红书/XHS** | 本地 Chrome CDP + cookie | 需 Chrome | 中等⁴ | ✅ 稳定 |\n| **知乎/Zhihu** | REST API v4 | ✅ | 正常 | ✅ 稳定 |\n| **知识星球/ZSXQ** | REST API v2 | ✅ | 正常 | ✅ 稳定 |\n| **微博/Weibo** | REST API | ✅ | 正常 | ✅ 稳定 |\n| **抖音/Douyin** ⚠️ | Chrome CDP + 验证码轮询 | 需 Chrome | 实验性⁵ | ⚠️ 实验性 |\n| **B站/Bilibili** | 公开 Web API | ✅ | 建议低频调用 | ✅ 稳定 |\n| **豆瓣/Douban** | 移动端 JSON API | ✅ | 搜索可能触发风控 | ⚠️ 依会话 |\n| **大众点评/Dianping** | 公开网页解析 | ✅ | 可能触发页面风控 | ⚠️ 依页面结构 |\n\n> ⁴ 小红书只允许住宅 IP——云浏览器/数据中心 IP 直接封。必须用本地 Chrome。\n> ⁵ 抖音搜索需要登录态 + 手动过滑块验证码。支持 120s 等待用户手动验证，通过后自动抓取。`guided_login(\"douyin\")` 可引导登录。\n\n## 快速开始\n\n### 安装\n\n```bash\npip install cn-scraper-mcp\n```\n\n也可以从源码安装开发版本：\n\n```bash\ngit clone https://github.com/goesByhc/cn-scraper-mcp.git\ncd cn-scraper-mcp\npip install .\n```\n\n### 推荐：CDP 自动登录并保存 Cookie\n\n安装并连接 MCP 后，直接让 Agent 调用：\n\n```text\nguided_login(platform=\"weibo\")\n```\n\n它会打开本地 Chrome 并进入平台官方登录页。你自己扫码或输入密码后，工具通过 CDP 自动读取完整 Cookie（包括 JavaScript 无法读取的 HttpOnly Cookie），再保存到本机 `~/.cn-scraper-cookies/`。京东则保存到本地持久化 Chrome Profile。\n\n这是推荐方式，因为它不会要求你复制 Cookie，不容易漏掉关键字段，也更适合 Cookie 过期后的重新登录。可用平台名包括 `taobao`、`jd`、`xiaohongshu`、`zhihu`、`weibo`、`zsxq`、`douyin`、`pdd`、`douban` 和 `dianping`。\n\n已有通过远程调试端口启动且登录完成的 Chrome 时，也可以调用：\n\n```text\nharvest_cookies(platform=\"weibo\")\n```\n\n### 启动\n\n```bash\ncn-scraper-mcp\n# 或: python -m cn_scraper_mcp.server\n```\n\n### Docker\n\n容器内预装 Chromium，无需本地浏览器：\n\n```bash\ndocker build -t cn-scraper-mcp .\ndocker run -i --rm \\\n -v ~/.cn-scraper-cookies:/root/.cn-scraper-cookies \\\n -v ~/.jd_login_profile:/root/.jd_login_profile \\\n cn-scraper-mcp\n```\n\n远程服务器部署可以切换到 HTTP transport，通过 `IP + 端口` 连接：\n\n```bash\ndocker pull ghcr.io/goesbyhc/cn-scraper-mcp:latest\ndocker run -d --name cn-scraper-mcp \\\n -p 8000:8000 \\\n -e CN_SCRAPER_TRANSPORT=http \\\n -e CN_SCRAPER_HOST=0.0.0.0 \\\n -e CN_SCRAPER_PORT=8000 \\\n -e CN_SCRAPER_PATH=/mcp \\\n -v ~/.cn-scraper-cookies:/root/.cn-scraper-cookies \\\n -v ~/.jd_login_profile:/root/.jd_login_profile \\\n ghcr.io/goesbyhc/cn-scraper-mcp:latest\n```\n\n远程 MCP endpoint：\n\n```text\nhttp://:8000/mcp\n```\n\n也可以使用 Docker Compose：\n\n```bash\ndocker compose --profile remote up -d cn-scraper-http\n```\n\n可用环境变量：\n\n| 变量 | 默认值 | 说明 |\n|------|------|------|\n| `CN_SCRAPER_TRANSPORT` | `stdio` | `stdio`、`http`、`sse`，也接受 `streamable-http` 作为 `http` 别名 |\n| `CN_SCRAPER_HOST` | `0.0.0.0` | HTTP/SSE 模式监听地址 |\n| `CN_SCRAPER_PORT` | `8000` | HTTP/SSE 模式监听端口 |\n| `CN_SCRAPER_PATH` | `/mcp` | HTTP/SSE MCP endpoint 路径 |\n\n> 远程 HTTP 模式会让 MCP 工具通过网络访问本机 Cookie/Profile 目录，请勿直接裸露公网端口。建议放在内网、VPN、防火墙白名单或带鉴权的反向代理后面。小红书、京东、抖音等依赖本地浏览器、住宅 IP 或人工验证码的平台，在远程服务器上的稳定性取决于服务器网络与图形环境。\n\n当平台要求人工处理登录、验证码或风控页时，工具会返回统一的 `ACTION_REQUIRED` 结构，并在 `action_required` 字段中说明平台、原因、处理动作、处理链接和建议重试的工具。当前抖音验证码已接入该结构；远程 Docker 场景下仍需要你通过可见浏览器或后续 noVNC 网页完成验证。\n\nAgent 集成配置：\n\n```toml\n# Codex ~/.codex/config.toml\n[mcp_servers.cn-scraper]\ncommand = \"docker\"\nargs = [\"run\", \"-i\", \"--rm\",\n \"-v\", \"/本机绝对路径/.cn-scraper-cookies:/root/.cn-scraper-cookies\",\n \"-v\", \"/本机绝对路径/.jd_login_profile:/root/.jd_login_profile\",\n \"cn-scraper-mcp\"]\n```\n\n请把 `/本机绝对路径/` 替换为真实路径；MCP 客户端直接启动进程时不会替你展开 `~`。\n\n> Docker 镜像内置 Chromium + `--no-sandbox`。京东 headful 模式如需 Xvfb，设置环境变量 `XVFB_WRAPPER=1`。小红书仍需住宅 IP——数据中心 IP 会被封。\n\n---\n\n## MCP 工具一览\n\n### 电商搜索\n\n| 工具 | 说明 |\n|------|------|\n| `taobao_search` | 淘宝/天猫关键词搜索 → 价格、销量、店铺 |\n| `taobao_product` | 淘宝商品详情 → 标题、价格、店铺 |\n| `jd_search` | 京东关键词搜索 → SKU、价格、商品名 |\n| `jd_product` | 京东商品详情 → 名称、价格、店铺、规格 |\n| `pdd_search` | 拼多多搜索 → 仅首次有效 |\n| `pdd_product_detail` | 拼多多商品详情 → 不限次数 |\n\n### 内容社区\n\n| 工具 | 说明 |\n|------|------|\n| `xiaohongshu_search` | 小红书笔记搜索 → 标题、作者、点赞、`noteId`、`xsec_token` |\n| `xiaohongshu_note` | 小红书笔记详情 → 标题、正文、作者、标签、互动数、发布时间 |\n| `xiaohongshu_comments` | 小红书笔记首屏评论 → 评论内容、用户、点赞、时间（需要 `noteId` + `xsec_token`） |\n| `zhihu_search` | 知乎搜索 → 问题、文章 |\n| `zhihu_hot_list` | 知乎热榜 |\n| `zhihu_comments` | 知乎回答评论（支持分页） |\n| `zhihu_answer` | 知乎回答完整正文 |\n| `zhihu_question_answers` | 知乎问题下的回答列表 |\n| `weibo_search` | 微博搜索 → 微博帖子内容 |\n| `weibo_hot_list` | 微博热搜榜 |\n| `weibo_user_timeline` | 微博用户时间线 |\n| `weibo_comments` | 微博帖子评论（支持分页） |\n| `weibo_post` | 微博帖子完整详情 |\n| `douyin_search` | 抖音搜索 → CDP 浏览器 + 验证码轮询（⚠️ 实验性） |\n| `douyin_hot_list` | 抖音热搜榜 |\n| `douyin_video` | 抖音视频详情 |\n| `douyin_comments` | 抖音视频评论 |\n| `bilibili_search` | B 站视频搜索（纯 HTTP，无需登录） |\n| `bilibili_popular` | B 站热门视频榜 |\n| `bilibili_video` | B 站视频详情及互动统计 |\n| `bilibili_comments` | B 站视频一级评论（支持分页） |\n| `douban_search` | 豆瓣书籍、电影、音乐等条目搜索 |\n| `douban_subject` | 豆瓣条目详情 |\n| `douban_reviews` | 豆瓣条目短评/影评 |\n| `dianping_search` | 大众点评商户搜索 |\n| `dianping_shop` | 大众点评商户详情 |\n| `dianping_reviews` | 大众点评商户评价 |\n| `zsxq_topics` | 知识星球付费社群帖子 |\n| `zsxq_article` | 知识星球文章全文 |\n\n### Cookie 管理\n\n| 工具 | 说明 |\n|------|------|\n| `check_cookies` | 检查所有平台 Cookie 状态 |\n| `verify_login` | 在线验证知乎、微博、知识星球、抖音登录态；不支持的平台明确返回 unsupported |\n| `diagnose` | 环境诊断——依赖版本、浏览器、CDP 端口 |\n| `harvest_cookies` | CDP 自动收割 Cookie（包括 HttpOnly） |\n| `guided_login` | 引导登录——自动打开浏览器 → 你扫码 → 登录后自动收割 Cookie |\n\n## MCP 客户端配置\n\n### Codex\n\n`~/.codex/config.toml`：\n\n```toml\n[mcp_servers.cn-scraper]\ncommand = \"cn-scraper-mcp\"\nargs = []\n```\n\n保存后可用 `codex mcp list` 检查连接状态。\n\n### Claude Code / Cursor / Reasonix\n\n这三个客户端都支持标准的 `mcpServers` JSON：\n\n- Claude Code：项目根目录 `.mcp.json`\n- Cursor：全局 `~/.cursor/mcp.json`，或项目目录 `.cursor/mcp.json`\n- Reasonix：项目根目录 `.mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"cn-scraper\": {\n \"command\": \"cn-scraper-mcp\",\n \"args\": []\n }\n }\n}\n```\n\n### Trae\n\nTrae 不同版本的配置文件位置可能不同。建议在设置中的 MCP 管理界面添加本地 stdio Server：名称填写 `cn-scraper`，命令填写 `cn-scraper-mcp`，参数留空。\n\n> 如果客户端提示找不到命令，先用 `where cn-scraper-mcp`（Windows）或 `which cn-scraper-mcp`（macOS/Linux）找到完整路径，再把 `command` 替换为该路径。\n\n---\n\n## 更多文档\n\n- [架构设计](https://github.com/goesByhc/cn-scraper-mcp/blob/master/docs/architecture.md)：职责边界、平台契约和 Agent 开发守则\n- [开发规范](https://github.com/goesByhc/cn-scraper-mcp/blob/master/CONTRIBUTING.md)：环境、编码、测试和 Review 要求\n\n---\n\n## 常见问题\n\n**Q: 使用这个软件安全吗？**\n软件在你的电脑上本地运行，不经过项目方的中转服务器。Cookie 和浏览器 Profile 保存在本机，Cookie 值不会写入日志或通过 MCP 返回给 Agent；需要访问平台时，凭证只发送给对应的平台域名。\n\n**Q: 软件会读取或保存账号密码吗？**\n不会。登录发生在平台官方页面，由你自己扫码或输入密码；工具只在登录完成后通过 CDP 保存浏览器产生的 Cookie。\n\n**Q: Cookie 保存在什么地方？**\nCookie 默认保存在 `~/.cn-scraper-cookies/`，京东使用本地持久化 Chrome Profile。请像保护已登录浏览器一样保护这些文件，不要分享或提交到 Git。\n\n**Q: 怎么初始化 Cookie 最方便？**\n用 `guided_login(\"平台名\")` 工具。它会自动打开 Chrome → 导航到登录页 → 等你扫码/输密码 → 登录后自动收割 Cookie 并保存。\n\n**Q: 合法吗？**\n仅用于**学习和研究目的**。批量抓取可能违反平台服务条款。风险自负。切勿用于垃圾信息、DDoS 或商业级大规模抓取。\n\n---\n\n## 许可证\n\nMIT — 详见 [LICENSE](https://github.com/goesByhc/cn-scraper-mcp/blob/master/LICENSE)。\n\n## 支持项目\n\n如果这个项目帮你节省了时间，可以请作者喝杯咖啡：\n\n

\n \"微信赞赏码\"\n

\n\n## 致谢\n\n- [curl_cffi](https://github.com/lexiforest/curl_cffi) — TLS 指纹伪装\n- [FastMCP](https://github.com/jlowin/fastmcp) — MCP Server 框架\n- [websockets](https://github.com/python-websockets/websockets) — 异步 WebSocket\n\n---\n\n*Made with ☕ and months of frustration at Chinese platform anti-bot walls.*\n", "bytes": 9262, "sha": "c568cad0b8a22d537906b4f2f59f516a5ad22c8b007fa010aacb097eaa9f391f", "repo_slug": "goesbyhc/cn-scraper-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_goesbyhc_cn_scraper_mcp_87485ca6/readme" }