@fysh925/mcp-server-fanqie

v0.1.2

Published

14 days ago

番茄小说 MCP 服务器 / A FanQie (Tomato) Novel MCP Server — 支持搜索、书籍详情、目录、章节内容、评论等 14 个工具

0High
0Medium
0Low

fysh925

mcp model-context-protocol fanqie tomato-novel 番茄小说 novel 小说 claude cursor llm ai

番茄小说 MCP 服务器

一个为番茄小说（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               # 说明文档

🔗 相关链接

📝 更新日志

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 支持一下！

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

番茄小说 MCP 服务器

✨ 功能特点

🛠️ 主要工具

1. search_books - 搜索书籍

2. get_book_detail - 获取书籍详情

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

4. get_simple_directory - 获取简化目录

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

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

7. get_comments - 获取评论

8. get_device_pool_status - 获取设备池状态

9. register_device - 注册设备

10. get_device_status - 获取设备状态

11. get_raw_content - 获取原始内容

12. get_ios_content - 获取 iOS 内容

13. register_ios_device - 注册 iOS 设备

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

📦 安装与使用

先决条件

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

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

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

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

🎯 使用示例

示例 1：搜索小说

示例 2：获取书籍详情

示例 3：获取书籍目录

示例 4：阅读章节内容

示例 5：批量获取章节

示例 6：获取评论

🔧 开发

构建项目

运行服务器

运行测试

使用 MCP Inspector 测试

📁 项目结构

🔗 相关链接

📝 更新日志

v0.1.2 (2026-06-13)

v0.1.1 (2026-06-13)

v0.1.0 (2025-01-16)

🤝 贡献

📄 许可证

🙏 致谢

⭐ Star History

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