eBook-mcp

Features# EPUB Support

• Extract metadata (title, author, publication date, etc.)
• Extract table of contents
• Extract chapter content (with Markdown output)
• Batch process EPUB files

PDF Support

• Extract metadata (title, author, creation date, etc.)
• Extract table of contents
• Extract content by page number
• Extract content by chapter title
• Markdown output support
• Batch process PDF files

Installation

1. Clone the repository:

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

2. Install dependencies using uv:

uv pip install -r requirements.txt

Usage# Starting the MCP Server in development mode

Run the server in development mode:

uv run mcp dev src/ebook_mcp/main.py

You can visit http://localhost:5173/ for testing & debugging purposes.

Starting the MCP Server in Prod mode

Run the server:

uv run src/ebook_mcp/main.py

Config the MCP in Cursor

Add the following configuration in Cursor:

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

EPUB Processing Examples

epub_files = get_all_epub_files("/path/to/books")\n\n# Get EPUB metadata
metadata = get_metadata("/path/to/book.epub")\n\n# Get table of contents
toc = get_toc("/path/to/book.epub")\n\n# Get specific chapter content (in Markdown format)
chapter_content = get_chapter_markdown("/path/to/book.epub", "chapter_id")

PDF Processing Examples

pdf_files = get_all_pdf_files("/path/to/books")\n\n# Get PDF metadata
metadata = get_pdf_metadata("/path/to/book.pdf")\n\n# Get table of contents
toc = get_pdf_toc("/path/to/book.pdf")\n\n# Get specific page content
page_text = get_pdf_page_text("/path/to/book.pdf", 1)
page_markdown = get_pdf_page_markdown("/path/to/book.pdf", 1)\n\n# Get specific chapter content
chapter_content, page_numbers = get_pdf_chapter_content("/path/to/book.pdf", "Chapter 1")

API Reference# EPUB APIs\n\n#### get_all_epub_files(path: str) -> List[str]

Get all EPUB files in the specified directory.\n\n#### get_metadata(epub_path: str) -> Dict[str, Union[str, List[str]]] Get metadata from an EPUB file.\n\n#### get_toc(epub_path: str) -> List[Tuple[str, str]] Get table of contents from an EPUB file.\n\n#### get_chapter_markdown(epub_path: str, chapter_id: str) -> str Get chapter content in Markdown format.

PDF APIs## get_all_pdf_files(path: str) -> List[str]

Get all PDF files in the specified directory.\n\n#### get_pdf_metadata(pdf_path: str) -> Dict[str, Union[str, List[str]]] Get metadata from a PDF file.\n\n#### get_pdf_toc(pdf_path: str) -> List[Tuple[str, int]] Get table of contents from a PDF file.\n\n#### get_pdf_page_text(pdf_path: str, page_number: int) -> str Get plain text content from a specific page.\n\n#### get_pdf_page_markdown(pdf_path: str, page_number: int) -> str Get Markdown formatted content from a specific page.\n\n#### get_pdf_chapter_content(pdf_path: str, chapter_title: str) -> Tuple[str, List[int]] Get chapter content and corresponding page numbers by chapter title.

Dependencies

Key dependencies include:

• ebooklib: EPUB file processing
• PyPDF2: Basic PDF processing
• PyMuPDF: Advanced PDF processing
• beautifulsoup4: HTML parsing
• html2text: HTML to Markdown conversion
• pydantic: Data validation
• fastmcp: MCP server framework

Important Notes

1. PDF processing relies on the document's table of contents. Some features may not work if TOC is not available.
2. For large PDF files, it's recommended to process by page ranges to avoid loading the entire file at once.
3. EPUB chapter IDs must be obtained from the table of contents structure.

Architecture

┌────────────────────────────┐
│ 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│
└────────────────────────────┘