coolapk-mcp

这是什么

coolapk-mcp 把酷安社区做成 MCP Server + CLI，让 AI 编程助手能：

开源自用维护中 · MIT · 当前 27★ / 5 fork

Related MCP server: zhihu-mcp

本 Fork 增强（2026-10-24）

• 风控规避管线：全局限速（默认 1.2s，COOLAPK_MIN_INTERVAL）+ GET TTL 缓存（COOLAPK_NO_CACHE=1 关闭）+ 瞬态退避重试 + 验证码负缓存，错误带 error_type 分类

• 数盟 ShuzlmID 设备码：auth/device.py 提供 encode_device_code/decode_device_code，用本机官方 App 的 SHUZILM_DID（root 读 prefs）+ 机型参数构造设备码，实测可解除 feed/detail、replyList 的 err_request_captcha_v2 拦截；替代已因多账号风控(-415)被拉黑的公共共享码

• 详情智能回落：detail 被风控时自动经 feed_id→uid 索引（持久化）从作者动态列表取正文，fetch_source 字段标注来源

• 搜索质量：默认严格关键词过滤（归一化匹配、去重、疑似广告标记），--no-strict 关闭

• 全量评论 + 关键词检索：coolapk feed <id> --all-replies / MCP all_replies=true 自动翻页拉全部一级评论（楼中楼内联）；--grep "词1 词2" / MCP comment_keyword 对评论与楼中楼做 OR 检索，命中带 comment_match 与 comment_search 统计

• 身份配置仍是 ~/.coolapk-mcp/config.json（设备码 + Cookie），详见 coolapk_mcp/auth/device.py 顶部注释

快速开始

# 需要 Python >= 3.10
git clone https://github.com/Lniosy/coolapk-mcp.git
cd coolapk-mcp
pip install -e .

装好后两条路任选：

1. MCP Server（推荐接 Cursor / Claude Desktop）

2. CLI（脚本、Agent Skill、管道调用更省 token）

功能

• 搜索 — 帖子、用户、话题、应用

• 帖子详情 — 完整内容 + 评论（见 已知限制）

• 用户资料 — 个人信息、发帖列表

• 首页动态 — 推荐 / 热门 / 最新

• 话题浏览 — 话题详情 + 话题下帖子

• 交互操作 — 点赞、回复、关注（需登录）

• 精简输出 — 自动排除空值字段，省 AI 上下文 token

• 图片 URL — 搜索/详情直接返回 images 列表（#1 已修）

Cursor / Claude 配置

Cursor（~/.cursor/mcp.json 或项目 .cursor/mcp.json）

{
  "mcpServers": {
    "coolapk": {
      "command": "coolapk-mcp"
    }
  }
}

若用本地源码路径：

{
  "mcpServers": {
    "coolapk": {
      "command": "python",
      "args": ["-m", "coolapk_mcp.server"],
      "cwd": "/绝对路径/coolapk-mcp"
    }
  }
}

Claude Code / Desktop

{
  "mcpServers": {
    "coolapk": {
      "command": "coolapk-mcp"
    }
  }
}

Claude Code Skill（更省 token）

项目内置 .claude/skills/coolapk.md，clone 进工作目录后 Claude Code 可直接当 skill 用；CLI 无协议开销，输出更紧凑。

注册的 MCP Tools

CLI 使用

所有命令输出紧凑 JSON，适合 AI 解析。

coolapk search "关键词"
coolapk search "用户名" --type user
coolapk feed <帖子ID>
coolapk feed <帖子ID> --no-replies
coolapk user <UID>
coolapk user <UID> --feeds
coolapk home --tab hot
coolapk topic "小米解锁BL"
coolapk topic "小米解锁BL" --feeds

交互操作（需登录）

coolapk login --cookie "uid=xxx;username=xxx;token=xxx"
coolapk like <帖子ID>
coolapk reply <帖子ID> -m "回复内容"
coolapk follow <UID>

生态适配

社区已有基于本项目的桌面端适配，欢迎继续扩展：

qxcoolapk — Qx 快捷启动器插件

@mcxen 将 Coolapk MCP 接口适配为 Qx（Mac / Windows 快捷启动器）沙盒插件 qxcoolapk，可在 Qx Workbench 里浏览热榜、数码动态、完整帖文、图片与回复。

授权与署名均 OK，欢迎继续使用与改进。原始讨论见 #4。

友链

想把 coolapk-mcp 接到你的产品？开个 Issue 或 PR，README 生态区欢迎挂友链。

已知限制

• /v6/feed/detail 验证码：新版酷安对详情接口风控更严，部分环境会稳定返回 err_request_captcha_v2；搜索、列表、用户动态、评论等读接口通常仍可用。详见 #5。临时思路：从作者动态列表按 ID 回落读公开帖（不保证字段完整）。

• 请合理使用接口频率，遵守酷安用户协议与当地法规；本项目仅作个人/研究向信息检索，不提供绕过风控或破解软件相关能力。

技术实现（简述）

• Token 生成与设备标识模拟，兼容公开 API 访问模式

• Pydantic 精简序列化（exclude_defaults=True），输出体积约为原始响应的约 10%

项目结构

coolapk_mcp/
├── server.py          # MCP Server 入口
├── cli.py             # CLI 入口
├── client.py          # HTTP 客户端 + API 封装
├── models.py          # Pydantic 数据模型
├── config.py          # 配置管理
└── auth/
    ├── token.py       # Token 生成
    └── device.py      # 设备码生成

致谢

• API 参考了 Coolapk-UWP/Coolapk-Lite

• 生态适配：mcxen/qx · mcxen/qx-plugins（qxcoolapk）

License

MIT