Server Fanqie

一个为番茄小说（FanQie Novel）提供 MCP（Model Context Protocol）服务的工具，支持将番茄小说的书籍、目录、章节内容等数据提供给支持 MCP 协议的大语言模型客户端，如 Claude Desktop、Cursor。

✨ 功能特点

• 🔍 搜索功能 - 支持搜索小说、听书、漫画、短剧
• 📖 书籍信息 - 获取书籍详情、完整目录、简化目录
• 📄 内容获取 - 获取章节内容，支持多种内容类型
• 💬 评论功能 - 获取书籍评论，支持分页
• 📱 设备管理 - 支持 Android 和 iOS 设备池管理
• 🎯 多平台支持 - 支持获取 iOS 平台特定内容

🛠️ 主要工具

1. search_books - 搜索书籍

搜索番茄小说平台上的书籍、听书、漫画或短剧。

参数：

• key (必需): 搜索关键词
• tab_type (可选): 内容类型
  • 3 - 小说（默认）
  • 2 - 听书
  • 8 - 漫画
  • 11 - 短剧
• offset (可选): 分页偏移量，默认为 0

示例：

搜索"修仙"关键词的小说
搜索"历史"关键词的漫画

2. get_book_detail - 获取书籍详情

获取指定书籍的详细信息，包括书名、作者、简介、封面等元数据。

参数：

• book_id (必需): 书籍 ID

返回信息：

• 书名、作者、译者
• 简介、封面
• 分类、标签
• 字数、评分等

3. get_book_directory - 获取书籍完整目录

获取书籍的完整章节目录列表，包括所有卷和章节信息。

参数：

• book_id (必需): 书籍 ID

返回信息：

• 所有卷的标题和 ID
• 每卷下的章节列表
• 章节标题和 ID

4. get_simple_directory - 获取简化目录

获取书籍的简化目录信息，仅包含章节标题和 ID。

参数：

• book_id (必需): 书籍 ID

用途：

• 快速获取章节列表
• 用于批量获取章节内容

5. get_chapter_content - 获取章节内容（简单接口）

获取指定章节的文本内容。

参数：

• item_id (必需): 章节 ID

返回：

• 章节文本内容

6. get_content - 获取内容（统一接口）

统一的内容获取接口，支持多种内容类型。

参数：

• tab (必需): 内容类型
  • novel - 小说章节
  • audiobook - 有声书音频
  • short drama - 短剧视频
  • comic - 漫画图片
  • batch - 批量获取多个章节
  • download - 下载整本小说
• item_id (可选): 单个章节/视频/漫画 ID（小说、听书、短剧、漫画时必需）
• item_ids (可选): 多个章节 ID，逗号分隔（批量时必需）
• book_id (可选): 书籍 ID（批量、下载时必需）
• show_html (可选): 漫画是否返回 HTML 格式（0 或 1，默认 0）
• tone_id (可选): 有声书音色 ID（听书时使用，默认 0）
• async (可选): 漫画异步模式（0 或 1，默认 1，建议为 1 以获得更快响应）

使用场景：

• 获取单个小说章节：tab=novel, item_id=章节ID
• 获取有声书音频：tab=audiobook, item_id=章节ID
• 获取漫画图片：tab=comic, item_id=章节ID
• 批量获取章节：tab=batch, item_ids=章节ID1,章节ID2, book_id=书籍ID
• 下载整本小说：tab=download, book_id=书籍ID

7. get_comments - 获取评论

获取书籍、章节或其他内容的评论列表，支持分页。

参数：

• book_id (必需): 书籍 ID
• count (可选): 每页数量，默认 20
• offset (可选): 偏移量，默认 0

8. get_device_pool_status - 获取设备池状态

查看设备池的整体状态，包括所有注册设备。

用途：

• 检查可用设备
• 监控设备健康状态

9. register_device - 注册设备

注册新的设备到设备池。

参数：

• platform (可选): 平台类型
  • android（默认）
  • ios

10. get_device_status - 获取设备状态

查看指定平台的设备状态。

参数：

• platform (可选): 平台类型
  • android（默认）
  • ios

11. get_raw_content - 获取原始内容

获取未处理的原始章节内容，包含完整的响应数据（HTML 格式、作者的话等）。

参数：

• item_id (必需): 章节 ID

用途：

• 需要原始 HTML 结构或完整字段时使用

12. get_ios_content - 获取 iOS 内容

使用 iOS 平台接口（8402 算法签名）获取章节内容。

参数：

• item_id (必需): 章节 ID

⚠️ 该接口依赖 iOS 设备池，上游服务可能临时不可用。

13. register_ios_device - 注册 iOS 设备

注册新的 iOS 设备到设备池。

参数： 无

⚠️ 该接口依赖上游 iOS 服务，可能临时不可用。

14. get_manga_progress - 查询漫画下载进度

根据任务 ID 查询漫画下载任务的进度。

参数：

• task_id (必需): 任务 ID（由漫画内容接口返回）

📦 安装与使用

✅ 本仓库已包含编译产物 build/，克隆或导入后无需自己编译即可直接运行。

先决条件

• Node.js 16.x 或更高版本（仅运行的话不需要装 TypeScript）

---

🚀 方式一：用 npx 一键配置（推荐，魔搭托管 / 本地客户端通用）

包已发布到 npm（@fysh925/mcp-server-fanqie），任何支持 MCP 的平台都用下面这一段配置——魔搭社区「可托管部署」、Claude Desktop、Cursor、Cherry Studio 全都适用：

{
  "mcpServers": {
    "fanqie-novel": {
      "command": "npx",
      "args": ["-y", "@fysh925/mcp-server-fanqie"]
    }
  }
}

• 魔搭社区：创建 MCP 服务 → 选「可托管部署」→ 配置里粘贴上面这段。魔搭云端会用 npx 自动从 npm 拉起服务，无需你自己的服务器，也无需下载代码。
• 本地客户端（Claude Desktop / Cursor / Cherry Studio）：把上面这段填进对应配置文件即可。

✅ 为什么用 npx：魔搭等平台的「可托管部署」需要从公共仓库（npm）拉起服务。npx 会自动下载并运行最新版 @fysh925/mcp-server-fanqie，这是云端托管最省心、最可靠的方式。如果填本地路径（node build/index.js），魔搭云端没有你的仓库文件，会部署失败并退化成「仅本地可用」。

部署后确认：能看到 14 个工具、调用 search_books 搜书能正常返回 —— 即成功。

各客户端配置文件位置：

• Claude Desktop：claude_desktop_config.json
• Cursor：~/.cursor/mcp.json 或项目内 .cursor/mcp.json
• Cherry Studio：设置 → MCP 服务器 → 编辑 JSON

改完配置后需完全退出并重启客户端才生效（刷新无效）。

---

💻 方式二：用本地源码运行（不想用 npx 时）

仓库已含编译产物 build/，克隆后即可运行，无需编译：

git clone https://github.com/fysh1010/mcp-server-fanqie.git

配置里用 node + 你克隆后的实际绝对路径：

{
  "mcpServers": {
    "fanqie-novel": {
      "command": "node",
      "args": ["/你的克隆路径/mcp-server-fanqie/build/index.js"]
    }
  }
}

• Windows 示例（反斜杠必须双写 \\）："args": ["C:\\Users\\你的用户名\\mcp-server-fanqie\\build\\index.js"]
• macOS / Linux 示例："args": ["/Users/你的用户名/mcp-server-fanqie/build/index.js"]

⚠️ 本地绝对路径只适用于本机客户端，不要填到魔搭等云平台（云端没有这个路径）。云平台请用方式一的 npx。

---

🔧 方式三：从源码自行编译（仅当你改了 src/ 源码时）

git clone https://github.com/fysh1010/mcp-server-fanqie.git
cd mcp-server-fanqie
npm install
npm run build      # 重新生成 build/

改完源码记得 npm run build 重新编译，并把 src/ 和 build/ 一起提交，否则托管平台运行的还是旧版本。

---

⚙️ 自定义 API 地址（可选）

服务默认使用内置接口地址 http://101.35.133.34:5000。若该地址日后变更，可通过环境变量 FANQIE_API_BASE 覆盖，无需改代码：

{
  "mcpServers": {
    "fanqie-novel": {
      "command": "npx",
      "args": ["-y", "@fysh925/mcp-server-fanqie"],
      "env": {
        "FANQIE_API_BASE": "http://新的接口地址:端口"
      }
    }
  }
}

也可在项目根目录创建 .env 文件：FANQIE_API_BASE=http://101.35.133.34:5000

🎯 使用示例

示例 1：搜索小说

用户：

帮我搜索关于修仙的小说

LLM 调用：

search_books(key="修仙", tab_type=3, offset=0)

返回结果：

{
  "keyword": "修仙",
  "tab_type": 3,
  "offset": 0,
  "results": [
    {
      "book_id": "7233628636023098407",
      "book_name": "修罗武神",
      "author": "善良的蜜蜂",
      "cover": "...",
      "abstract": "...",
      "total_words": 1000000
    }
    // ... 更多搜索结果
  ]
}

示例 2：获取书籍详情

用户：

帮我查看《修罗武神》的详细信息

LLM 调用：

get_book_detail(book_id="7233628636023098407")

返回结果：

{
  "book_id": "7233628636023098407",
  "detail": {
    "book_name": "修罗武神",
    "author": "善良的蜜蜂",
    "abstract": "一个关于修仙的故事...",
    "cover": "...",
    "total_words": 1000000,
    "rating": 8.5,
    "category": "玄幻"
  }
}

示例 3：获取书籍目录

用户：

帮我获取《修罗武神》的目录

LLM 调用：

get_book_directory(book_id="7233628636023098407")

返回结果：

{
  "book_id": "7233628636023098407",
  "directory": {
    "volume_1": {
      "volume_id": "xxx",
      "volume_title": "第一卷",
      "chapters": [
        {"chapter_id": "xxx", "chapter_title": "第一章"},
        {"chapter_id": "xxx", "chapter_title": "第二章"}
      ]
    }
  }
}

示例 4：阅读章节内容

用户：

我想读《修罗武神》的第一章

LLM 调用：

get_chapter_content(item_id="7233628684760910863")

返回结果：

{
  "item_id": "7233628684760910863",
  "content": "第一章的内容..."
}

示例 5：批量获取章节

用户：

帮我获取《修罗武神》前 5 章的内容

LLM 调用：

get_content(tab="batch", item_ids="章节ID1,章节ID2,章节ID3,章节ID4,章节ID5", book_id="7233628636023098407")

示例 6：获取评论

用户：

《修罗武神》有什么热门评论？

LLM 调用：

get_comments(book_id="7233628636023098407", count=10, offset=0)

🔧 开发

构建项目

git clone https://github.com/fysh1010/mcp-server-fanqie.git
cd mcp-server-fanqie
npm install
npm run build

运行服务器

npm run start

运行测试

npm test

使用 MCP Inspector 测试

npm run inspector

📁 项目结构

mcp-server-fanqie/
├── src/
│   ├── FanQieApi.ts        # 番茄小说 API 封装类
│   ├── fontDecrypt.ts      # 字体解密模块（备用）
│   └── index.ts            # MCP 服务器主入口
├── build/                  # 编译产物（已纳入版本控制，可直接运行）
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript 配置
├── .gitignore              # Git 忽略文件
└── README.md               # 说明文档

🔗 相关链接

• 番茄小说官网
• 番茄小说 API 文档
• 本项目 npm 包
• 本项目 GitHub 仓库
• MCP 协议规范

📝 更新日志

v0.1.2 (2026-06-13)

• 📄 补全 LICENSE 文件（MIT）
• 🏷️ 完善 package.json 元数据（author / repository / homepage / bugs / keywords / engines）
• ⭐ README 加入 Star History 星标曲线图

v0.1.1 (2026-06-13)

• 📦 已发布到 npm：@fysh925/mcp-server-fanqie，可用 npx -y @fysh925/mcp-server-fanqie 一键部署到魔搭等平台
• 🔧 更新 API 接口地址（原地址已失效）至 http://101.35.133.34:5000
• ⚙️ 支持通过环境变量 FANQIE_API_BASE 自定义 API 地址，接口变更时无需改动代码
• ✨ get_content 新增 download 整本下载类型及 async 漫画异步模式参数
• ➕ 补全 4 个此前未暴露的工具（接口文档共 14 个，现已全部封装为 MCP 工具）：
  • get_raw_content - 获取原始内容
  • get_ios_content - 获取 iOS 内容
  • register_ios_device - 注册 iOS 设备
  • get_manga_progress - 查询漫画下载进度

v0.1.0 (2025-01-16)

• 🎉 首次发布
• ✅ 实现搜索功能
• ✅ 实现书籍信息获取
• ✅ 实现目录和章节内容获取
• ✅ 实现评论功能
• ✅ 实现设备管理功能
• ✅ 支持 iOS 平台特定内容获取

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

本项目基于 番茄小说 API 开发

• MCP SDK
• 项目结构参考了社区中其他 MCP 服务器的开发实践

⭐ Star History

如果这个项目对你有帮助，欢迎点个 Star 支持一下！

Star History Chart

---

注意： 本项目仅供学习和研究使用，请遵守番茄小说的使用条款和 API 使用规范。