fanqie-mcp

让你的 Agent 查询番茄作家课堂，以及你自己的作品、经营数据和草稿。

这是一个自行部署的番茄作者平台 MCP 服务。服务在本机运行，Codex、Claude Code 等 Agent Host 通过 HTTP 调用它；你在客户端用自然语言提出需求即可。服务也提供 REST API，供程序接入。

这是独立开发的早期项目，与番茄官方无隶属关系。当前版本以查询为主，写操作默认关闭。

可以用它做什么

连接后，可以直接对 Agent 说：

“列出番茄作家课堂的写作技巧课程，选一篇读给我。”
“确认当前登录的番茄账号是谁，再列出我的短故事作品。”
“查看我的作品经营数据，说明统计口径和数据截止时间。”
“读取这部作品的章节目录和草稿。”
“查看上一次保存的账号数据，不重新访问平台。”

能力	是否需要番茄登录	当前范围
作家课堂目录与文章	否	五个分类、文章文字和图片链接；不转写视频或图片
官方活动	否	平台公开活动资料
本人短故事、长篇作品及经营指标	是	全分页读取、完整性检查、历史快照
本人章节目录与草稿	是	当前账号可访问的管理目录及草稿箱
本人章节、短故事正文	是	作者当前编辑版本；不证明与已发布正文一致
已保存数据与任务结果	有本地数据即可	明确标记为历史，不伪装实时数据
草稿维护、投稿与发布	是，且需独立能力	已有适配代码；默认关闭，真实投稿闭环尚未验证

查询能力已有真实平台读取记录，平台页面和接口变化后仍可能失效。部署后以 fanqie_get_capabilities 和本次任务结果为准；工具出现在列表里不等于当前一定可用。

开始使用

推荐 Docker Compose。需要 Git、Node.js 22.13+、Yarn 1.22.22 和支持 Linux 容器的 Docker。

git clone https://github.com/Nuibia/fanqie-mcp.git
cd fanqie-mcp
node scripts/init-secrets.mjs
docker compose up -d --build
curl --fail http://127.0.0.1:18062/health

首次构建会下载依赖和浏览器镜像、准备固定测试资料并运行检查，可能需要数分钟。源码仓库的公开发行状态以 Release 为准。也可按固定版本镜像安装直接启动，无需本机 Node/Yarn；可用架构和固定 digest 以版本发行说明为准。

健康检查应返回 status: "ok"。接下来在 Agent Host 中连接：

配置项	值
传输	Streamable HTTP
MCP 地址	`http://127.0.0.1:18062/mcp`
鉴权	`Authorization: Bearer <服务 Token>`
Token 所在文件	`.secrets/api-token`
建议单次工具等待时间	至少 135 秒

完整步骤看快速开始，客户端配置看接入教程。 服务 Token 只用于连接本服务；番茄账号登录通过本人扫码完成，两者是不同操作。

第一次使用可以照着完整演示完成连接 → 公开课程 → 扫码与身份核验 → 本人作品 → 历史读取；日常查询直接复制五份提示词。示例结果均使用合成数据。

三个常见问题

没有登录能用吗？ 可以查作家课堂和官方活动。查自己的作品、指标和草稿需要登录。

登录了为什么显示 unknown？ 服务重启后，还没有实际检查登录时也会显示 unknown。让 Agent 调用 fanqie_check_login_status：它会访问平台核验，并返回账号昵称、ID 和检查时间。unknown 本身不代表已经退出登录。

能看别人的作品后台吗？ 本人数据接口只读取服务登录账号可访问的数据。本服务不提供全站小说爬取或他人经营数据查询。

文档导航

文档	解决的问题
快速开始	安装、首次查询、扫码登录和身份核验
客户端接入	Codex、Claude Code 的配置与连接验证
固定版本镜像	免开发环境安装、固定版本与升级
完整演示	每一步说什么、成功结果长什么样
五份提示词	课程、作品、指标、章节与历史的日常查询
工具参考	当前 40 个工具、常用参数与结果含义
排障说明	登录、401/403、超时、部分结果和安装问题
配置与运维	环境变量、数据保存、升级和备份
架构说明	开发者如何理解服务模块
贡献指南	源码开发、离线测试和提交要求
安全策略	私有数据和漏洞报告
第三方说明	依赖、开发测试缓存和许可证边界
变更记录	当前版本与后续变化

项目定位与数据

MCP /mcp 与 REST /api/v1/ 共用业务、独立 Chromium 会话、SQLite 任务与证据存储。本仓不提供工作台界面；外部工作台可以通过 REST 接入。

.secrets/、.runtime/、浏览器登录态、正文、截图、二维码、备份和 Docker 数据卷都是私有数据。Compose 默认仅绑定本机地址。普通 docker compose down 保留数据卷；docker compose down -v 会删除它。

通过 Agent 查询时，MCP 返回的账号信息、作品资料或正文会进入所接入 Host 的对话，并可能发送给其模型服务；接入前确认该 Host 的数据处理方式。

原创代码与文档采用 MIT License。第三方平台资料和依赖保留各自权利。package.json 的 private: true 用于防止意外发布到 npm，不影响源码开源。