Ebook-MCP

<img src="logo.png" alt="ebook-mcp logo" width="132" height="132">

English | 中文

Ebook-MCP 是一个强大的模型上下文协议 (MCP) 服务器，用于处理电子书。它基于 模型上下文协议 构建，提供了一组标准化的 API，用于 LLM 应用程序和电子书处理能力之间的无缝集成。目前支持 EPUB 和 PDF 格式。

用例 & 价值

Ebook-MCP 通过启用与阅读材料的自然语言对话，改变了您与数字图书的交互方式。它可以与现代 AI 驱动的 IDE（如 Cursor 和 Claude）无缝集成，从而允许您：

• 智能图书馆管理：只需询问“显示我下载文件夹中的所有 EPUB 文件”或“在我的图书馆中查找有关 GenAI 的书籍”
• 互动式阅读体验：就您的书籍进行自然对话：
  • “简要介绍一下 'LLM Engineer Handbook'”
  • “第 3 章涵盖了哪些内容？”
  • “总结一下本书中关于 RAG 的要点”
• 主动学习支持：通过 AI 驱动的互动增强您的学习：
  • “根据第 5 章中的 RAG 概念创建一个测验”
  • “解释本章讨论的架构之间的差异”
  • “根据本节中的概念给我一些实践练习”
• 内容导航：通过自然语言查询轻松浏览您的书籍：
  • “查找所有讨论提示工程的部分”
  • “显示关于微调的章节”
  • “带我到关于向量数据库的部分”

通过弥合传统电子书和 AI 功能之间的差距，Ebook-MCP 帮助读者通过直观的、基于对话的互动，从他们的数字图书馆中提取更多价值。

特性

EPUB 支持

• 提取元数据（标题、作者、出版日期等）
• 提取目录
• 提取章节内容（带有 Markdown 输出）
• 批量处理 EPUB 文件

PDF 支持

• 提取元数据（标题、作者、创建日期等）
• 提取目录
• 按页码提取内容
• 按章节标题提取内容
• 支持 Markdown 输出
• 批量处理 PDF 文件

安装

1. 克隆存储库：

git clone https://github.com/yourusername/ebook-mcp.git
cd ebook-mcp

2. 使用 uv 安装依赖项：

uv pip install -r requirements.txt

使用

在开发模式下启动 MCP 服务器

在开发模式下运行服务器：

uv run mcp dev main.py

您可以访问 http://localhost:5173/ 进行测试和调试

在生产模式下启动 MCP 服务器

运行服务器：

uv run main.py

在 Cursor 中配置 MCP

在 Cursor 中添加以下配置

"ebook-mcp":{
            "command": "uv",
            "args": [
                "--directory",
                "/Users/onebird/github/ebook-mcp",
                "run",
                "main.py"
            ]
        }

EPUB 处理示例

# 获取目录中的所有 EPUB 文件
epub_files = get_all_epub_files("/path/to/books")

# 获取 EPUB 元数据
metadata = get_metadata("/path/to/book.epub")

# 获取目录
toc = get_toc("/path/to/book.epub")

# 获取特定章节内容（Markdown 格式）
chapter_content = get_chapter_markdown("/path/to/book.epub", "chapter_id")

PDF 处理示例

# 获取目录中的所有 PDF 文件
pdf_files = get_all_pdf_files("/path/to/books")

# 获取 PDF 元数据
metadata = get_pdf_metadata("/path/to/book.pdf")

# 获取目录
toc = get_pdf_toc("/path/to/book.pdf")

# 获取特定页面内容
page_text = get_pdf_page_text("/path/to/book.pdf", 1)
page_markdown = get_pdf_page_markdown("/path/to/book.pdf", 1)

# 获取特定章节内容
chapter_content, page_numbers = get_pdf_chapter_content("/path/to/book.pdf", "Chapter 1")

API 参考

EPUB APIs

get_all_epub_files(path: str) -> List[str]

获取指定目录中的所有 EPUB 文件。

get_metadata(epub_path: str) -> Dict[str, Union[str, List[str]]]

从 EPUB 文件获取元数据。

get_toc(epub_path: str) -> List[Tuple[str, str]]

从 EPUB 文件获取目录。

get_chapter_markdown(epub_path: str, chapter_id: str) -> str

以 Markdown 格式获取章节内容。

PDF APIs

get_all_pdf_files(path: str) -> List[str]

获取指定目录中的所有 PDF 文件。

get_pdf_metadata(pdf_path: str) -> Dict[str, Union[str, List[str]]]

从 PDF 文件获取元数据。

get_pdf_toc(pdf_path: str) -> List[Tuple[str, int]]

从 PDF 文件获取目录。

get_pdf_page_text(pdf_path: str, page_number: int) -> str

从特定页面获取纯文本内容。

get_pdf_page_markdown(pdf_path: str, page_number: int) -> str

从特定页面获取 Markdown 格式的内容。

get_pdf_chapter_content(pdf_path: str, chapter_title: str) -> Tuple[str, List[int]]

按章节标题获取章节内容和相应的页码。

依赖项

主要依赖项包括：

• ebooklib: EPUB 文件处理
• PyPDF2: 基本 PDF 处理
• PyMuPDF: 高级 PDF 处理
• beautifulsoup4: HTML 解析
• html2text: HTML 到 Markdown 转换
• pydantic: 数据验证
• fastmcp: MCP 服务器框架

重要提示

1. PDF 处理依赖于文档的目录。如果 TOC 不可用，某些功能可能无法工作。
2. 对于大型 PDF 文件，建议按页面范围处理，以避免一次加载整个文件。
3. EPUB 章节 ID 必须从目录结构中获取。

架构

           ┌────────────────────────────┐
           │         Agent Layer        │
           │  - Translation Strategy    │
           │  - Style Consistency Check │
           │  - LLM Call & Interaction │
           └────────────▲─────────────┘
                        │ Tool Calls
           ┌────────────┴─────────────┐
           │        MCP Tool Layer     │
           │  - extract_chapter        │
           │  - write_translated_chapter│
           │  - generate_epub          │
           └────────────▲─────────────┘
                        │ System/IO Calls
           ┌────────────┴─────────────┐
           │     System Base Layer     │
           │  - File Reading          │
           │  - ebooklib Parsing      │
           │  - File Path Storage/Check│
           └────────────────────────────┘

贡献

欢迎 Issues 和 Pull Requests！

更新日志

v1.0.0

• 首次发布
• 支持 EPUB 和 PDF 格式
• 基本文件处理 API

           ┌────────────────────────────┐
           │         Agent Layer        │
           │  - Translation Strategy    │
           │  - Style Consistency Check │
           │  - LLM Call & Interaction │
           └────────────▲─────────────┘
                        │ Tool Calls
           ┌────────────┴─────────────┐
           │        MCP Tool Layer     │
           │  - extract_chapter        │
           │  - write_translated_chapter│
           │  - generate_epub          │
           └────────────▲─────────────┘
                        │ System/IO Calls
           ┌────────────┴─────────────┐
           │     System Base Layer     │
           │  - File Reading          │
           │  - ebooklib Parsing      │
           │  - File Path Storage/Check│
           └────────────────────────────┘