Overview

This lightweight MCP (Model Context Protocol) server makes PDF and EPUB ebooks accessible to LLMs and agent workflows. It exposes a small HTTP API that ingests, parses, and serves ebook content in chunked, metadata-rich form so models can retrieve relevant passages, answer questions, and drive chat-based reading assistants. The server focuses on simplicity and interoperability with existing toolchains: it supports common ebook formats, integrates with vector stores and embedding providers, and implements MCP-compatible endpoints for context retrieval.

For developers building AI reading tools, the server reduces the plumbing required to convert binary ebook files into model-friendly context. Instead of handling parsing, chunking, and storage yourself, you can deploy this server locally or in a container and let it provide document-level search, passage retrieval, and lightweight metadata APIs that LLMs or frontend apps can call directly.

Features

Ingest and parse PDF and EPUB files into chunked text passages
Produce metadata (document id, chapter, page ranges, offsets) per chunk
Expose MCP-style endpoints for retrieving context and performing tool-like operations
Optional embedding/vector store integration for semantic search
Configurable chunk size, overlap, and parsing options
Docker-ready, minimal Python dependencies, and single-process server
Example request patterns for chat-based ebook assistants
Simple auth and environment-based configuration for API keys and providers

Installation / Configuration

Prerequisites: Python 3.10+, git, and optionally Docker.

Clone and install locally:

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

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Set configuration via environment variables (create a .env file or export in shell). Common variables:

# .env example
PORT=8080
HOST=0.0.0.0

# Optional: embedding provider keys
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Optional: vector store configuration
VECTOR_STORE=faiss
VECTOR_STORE_PATH=/data/faiss.index

# Authentication (optional)
API_KEY=your_api_key_here

Run the server with Uvicorn:

uvicorn app.main:app --host ${HOST:-0.0.0.0} --port ${PORT:-8080} --reload

Run with Docker:

docker build -t ebook-mcp .
docker run -p 8080:8080 --env-file .env ebook-mcp

Available Resources

The server provides a set of reusable components and HTTP resources useful for building an AI reading assistant:

Parser: PDF and EPUB parsers that extract text, chapter structure, and page ranges.
Chunker: Splits documents into overlapping passages (configurable size and overlap).
Metadata: Per-chunk metadata including document id, source file, chapter, page, and offsets.
Retriever: Configurable retrieval layer (brute-force text search or semantic search via embeddings + vector store).
Embedding hooks: Integration points for common embedding providers (OpenAI, local models).
MCP HTTP API: Endpoints for uploading/ingesting documents, listing documents, and retrieving context or passages for a query.

Example of a typical endpoint pattern (replace base path with your host/port):

POST /upload — upload a PDF/EPUB file
POST /ingest — trigger parsing & chunking for an uploaded file
GET /documents — list available documents and metadata
POST /retrieve — retrieve top-k chunks for a text query
POST /mcp/context — obtain an MCP-style context payload for model consumption

Example curl to retrieve relevant passages:

curl -X POST "http://localhost:8080/retrieve" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc-123",
    "query": "Explain the protagonist's motivation in chapter 3",
    "top_k": 5
  }'

Response: JSON with ranked chunks and metadata ready to be injected into a model prompt.

Use Cases

Chat-based ebook reader
- Build a web or mobile chat UI that queries the MCP server for relevant passages and composes model prompts for conversational Q&A about the ebook.
Study assistant and summarization
- Automatically retrieve chapter-level chunks and run summarization or flashcard generation pipelines with an LLM.
Highlighted note export
- Let users highlight passages in a reader UI, then use the MCP server to map highlights to chunks and export structured annotations.
Context-aware agents
- Combine the MCP retrieval API with a reasoning agent: the agent asks the server for passages as “tools” and then decides on next actions (search, quote, annotate).
Scalability testing and prototyping
- Lightweight server is suited for local prototyping before integrating a more complex ingestion pipeline or enterprise vector database.

Tips for Developers

Tune chunk size and overlap based on your model’s context window and the document type (dense technical content benefits from smaller chunks).
Use embeddings + a vector store for semantic search when document queries are abstract or paraphrased.
Store original file metadata (ISBN, author, title) alongside chunks to provide rich citations in model responses.
Implement rate limiting or API keys in production to protect hosted models and embedding costs.

For more examples and code snippets, consult the repository README and the example clients in the repo to see upload, ingest, and retrieval flows implemented end-to-end.

Lightweight EBook MCP Server for PDF and EPUB