Skip to main content
Glama
deenesjakoruzh
donghch

EPUB Reader MCP Server

by donghch
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

EPUB Reader MCP Server

License MCP Version Node.js Version

A Model Context Protocol (MCP) server that acts as a "Kindle for AI agents," exposing EPUB file content through standard MCP protocol operations and the Tools API.

Overview

The EPUB Reader MCP server provides AI agents with the ability to read and navigate EPUB files. It implements the Model Context Protocol (MCP) to expose 13 tools, and now follows the standard MCP handshake/discovery flow so clients like OpenClaw can initialize, list tools, and call them normally.

Features

  • Open EPUB files: Validate and parse EPUB files, create reading sessions

  • Navigate content: Move forward/backward through pages, jump to specific pages or chapters

  • Discover content: View table of contents, metadata, and chapter summaries

  • Search functionality: Full-text search across chapters with context

  • Reference tools: Resolve footnote references, get reading position

  • Session management: List open books, close sessions, manage resources

Prerequisites

  • Node.js 20+

  • npm or compatible package manager

  • EPUB files to read (.epub format)

Installation

From Source

git clone https://github.com/your-username/mcp-epub-reader.git
cd mcp-epub-reader
npm install
npm run build

Usage

Running the Server

The server uses stdio transport, making it ideal for local MCP clients (including OpenClaw).

stdio (Local Integration)

For integration with OpenClaw or other MCP clients:

node build/index.js

The server communicates via stdin/stdout using the MCP JSON-RPC protocol and supports standard MCP operations like initialization, tools/list, tools/call, and ping.

Configuration

OpenClaw Quick Start (recommended)

OpenClaw can connect to MCP servers over stdio. Add this server in OpenClaw’s MCP settings (exact location may vary). Tool discovery now works through standard MCP tools/list, so no custom wiring is needed.

Example (stdio):

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-epub-reader/build/index.js"]
}

Then use the tools like this:

  1. Open an EPUB

{
  "method": "tools/call",
  "params": {
    "name": "ebook__open",
    "arguments": {
      "filePath": "/path/to/book.epub",
      "autoNavigate": true
    }
  }
}

  1. Navigate

{
  "method": "tools/call",
  "params": {
    "name": "ebook__navigate_next",
    "arguments": {
      "sessionId": "<sessionId>"
    }
  }
}

  1. Search

{
  "method": "tools/call",
  "params": {
    "name": "ebook__search",
    "arguments": {
      "sessionId": "<sessionId>",
      "query": "adventure",
      "limit": 10,
      "contextWindow": 80
    }
  }
}

Security notes

This server validates filePath (prevents traversal), validates EPUB type (requires .epub + ZIP magic bytes), wraps the callback-based EPUB chapter API safely, and strips HTML from search snippets.

Environment Variables

Variable

Description

Required

Default

LOG_LEVEL

Logging level (error, warn, info, debug)

No

info

Tools Reference

Tools are published through MCP discovery, so clients can enumerate them automatically before calling them.

The server provides 13 tools for EPUB file interaction:

Tool

Description

Input Parameters

ebook__open

Open an EPUB file and create a reading session

filePath: string, autoNavigate?: boolean

ebook__close

Close a reading session and release resources

sessionId: string

ebook__list_open_books

List all currently open EPUB sessions

(none)

ebook__navigate_next

Move to the next page in the current session

sessionId: string

ebook__navigate_previous

Move to the previous page in the current session

sessionId: string

ebook__jump_to_page

Jump to a specific page number

sessionId: string, page: number

ebook__jump_to_chapter

Jump to a specific chapter

sessionId: string, chapterId: string

ebook__get_position

Get current reading position and progress

sessionId: string

ebook__search

Search across all chapters for text

sessionId: string, query: string, caseSensitive?: boolean, limit?: number, contextWindow?: number

ebook__get_toc

Get hierarchical table of contents

sessionId: string

ebook__get_metadata

Get EPUB metadata (title, author, publisher, etc.)

sessionId: string

ebook__get_footnote

Resolve a footnote reference by ID

sessionId: string, footnoteId: string

ebook__get_chapter_summary

Get a summary of the current chapter

sessionId: string, maxSentences?: number

Tool Details

ebook__open

Opens an EPUB file, parses its content, creates a reading session, and returns metadata.

Input Schema:

{
  filePath: string;      // Absolute or relative path to EPUB file
  autoNavigate?: boolean; // Whether to auto-navigate to first page (default: false)
}

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ebook__open",
    "arguments": {
      "filePath": "/path/to/book.epub",
      "autoNavigate": true
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"sessionId\":\"sess_123\",\"metadata\":{\"title\":\"Sample Book\",\"author\":\"Author Name\",\"totalPages\":250,\"totalChapters\":12}}"
      }
    ]
  }
}

ebook__close

Closes a reading session and releases associated resources.

Input Schema:

{
  sessionId: string;  // Session ID returned by ebook__open
}

ebook__list_open_books

Lists all currently active reading sessions.

Input Schema: (none)

Example Response:

{
  "sessions": [
    {
      "sessionId": "sess_123",
      "filePath": "/path/to/book.epub",
      "metadata": {
        "title": "Sample Book",
        "author": "Author Name",
        "currentPage": 42,
        "totalPages": 250
      }
    }
  ]
}

ebook__navigate_next and ebook__navigate_previous

Navigate forward or backward through pages.

Input Schema:

{
  sessionId: string;
}

Example Response:

{
  "sessionId": "sess_123",
  "currentPage": 43,
  "content": "Page content here...",
  "chapterTitle": "Chapter 3: The Adventure Begins"
}

ebook__jump_to_page

Jump to a specific page number.

Input Schema:

{
  sessionId: string;
  page: number;  // 1-based page number
}

ebook__jump_to_chapter

Jump to a specific chapter by chapterId (from the EPUB flow entry).

Input Schema:

{
  sessionId: string;
  chapterId: string;  // Chapter identifier from EPUB flow
}

ebook__get_position

Get current reading position and progress statistics.

Example Response:

{
  "sessionId": "sess_123",
  "currentPage": 42,
  "totalPages": 250,
  "progress": 0.168,
  "chapterTitle": "Chapter 3: The Adventure Begins",
  "chapterIndex": 3
}

ebook__search

Search across all chapters for text, with optional context words.

Input Schema:

{
  sessionId: string;
  query: string;
  caseSensitive?: boolean;
  limit?: number;
  contextWindow?: number;
}

Example Response:

{
  "sessionId": "sess_123",
  "query": "adventure",
  "matches": [
    {
      "chapterIndex": 3,
      "chapterTitle": "Chapter 3: The Adventure Begins",
      "pageNumber": 42,
      "context": "...the great adventure began when...",
      "position": 1250
    }
  ],
  "totalMatches": 1
}

ebook__get_toc

Get hierarchical table of contents.

Example Response:

{
  "sessionId": "sess_123",
  "toc": [
    {
      "title": "Chapter 1: Introduction",
      "level": 1,
      "pageNumber": 1,
      "children": []
    },
    {
      "title": "Part I: The Beginning",
      "level": 1,
      "pageNumber": 10,
      "children": [
        {
          "title": "Chapter 2: First Steps",
          "level": 2,
          "pageNumber": 12,
          "children": []
        }
      ]
    }
  ]
}

ebook__get_metadata

Get complete EPUB metadata.

Example Response:

{
  "sessionId": "sess_123",
  "metadata": {
    "title": "Sample Book",
    "author": "Author Name",
    "publisher": "Publisher Name",
    "description": "Book description...",
    "language": "en",
    "publishedDate": "2023-01-01",
    "totalPages": 250,
    "totalChapters": 12
  }
}

ebook__get_footnote

Resolve a footnote reference by ID.

Input Schema:

{
  sessionId: string;
  footnoteId: string;  // Footnote reference ID (e.g., "fn1")
}

Example Response:

{
  "sessionId": "sess_123",
  "footnoteId": "fn1",
  "content": "Footnote content here...",
  "referencingPage": 42
}

ebook__get_chapter_summary

Get a summary of the current chapter using key sentence extraction.

Input Schema:

{
  sessionId: string;
  maxSentences?: number;  // Maximum sentences in summary (default: 3)
}

Example Response:

{
  "sessionId": "sess_123",
  "chapterTitle": "Chapter 3: The Adventure Begins",
  "summary": [
    "The protagonist begins their journey.",
    "They encounter their first challenge.",
    "A mysterious figure offers guidance."
  ]
}

Development

Project Structure

mcp-epub-reader/
├── src/
│   ├── epub/                    # EPUB domain logic
│   │   ├── parser.ts           # EPUB parsing and metadata extraction
│   │   ├── paginator.ts        # Page splitting and content retrieval
│   │   └── types.ts            # EPUB domain types
│   ├── server/                 # MCP server implementation
│   │   ├── index.ts           # Server entry point (stdio transport)
│   │   ├── book-manager.ts    # Session lifecycle management
│   │   ├── tool-registration.ts # Tool registration and routing
│   │   └── types.ts           # Server-side types
│   ├── tools/                  # All 13 tool implementations
│   │   ├── open.ts            # ebook__open tool
│   │   ├── close.ts           # ebook__close tool
│   │   ├── list-books.ts      # ebook__list_open_books tool
│   │   ├── navigate.ts        # Navigation tools (next/previous)
│   │   ├── jump.ts            # Jump tools (page/chapter)
│   │   ├── position.ts        # ebook__get_position tool
│   │   ├── search.ts          # ebook__search tool
│   │   ├── toc.ts             # ebook__get_toc tool
│   │   ├── metadata.ts        # ebook__get_metadata tool
│   │   ├── footnote.ts        # ebook__get_footnote tool
│   │   └── summary.ts         # ebook__get_chapter_summary tool
│   └── utils/                  # Shared utilities
│       └── validation.ts      # Zod schemas and input validation
├── tests/                      # Test suites
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── package.json
├── tsconfig.json
└── jest.config.js

Building from Source

# Install dependencies
npm install

# Build the project (TypeScript → JavaScript)
npm run build

# Output goes to `build/` directory

Testing

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- tests/unit/epub/parser.test.ts

Adding a New Tool

  1. Create a new file in src/tools/ with the tool implementation:

// src/tools/example.ts
import { BookManager } from '../server/book-manager';
import { ExampleToolInput, ExampleToolOutput } from '../server/types';

export async function handleExampleTool(
  input: ExampleToolInput,
  bookManager: BookManager
): Promise<ExampleToolOutput> {
  // Tool implementation
  return { result: 'success' };
}

export function createExampleTool(bookManager: BookManager) {
  return {
    name: 'ebook__example' as const,
    handler: (input: ExampleToolInput) => handleExampleTool(input, bookManager),
  };
}

  1. Add Zod schema in src/utils/validation.ts:

export const ExampleToolSchema = z.object({
  sessionId: z.string(),
  // ... other parameters
});

  1. Import and register in src/server/tool-registration.ts:

import { createExampleTool } from '../tools/example';

const toolFactories = {
  // ... existing tools
  'ebook__example': createExampleTool,
};

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/your-username/mcp-epub-reader.git
cd mcp-epub-reader

# Install dependencies
npm install

# Set up environment
cp .env.example .env  # if applicable

# Run development server with watch mode
npm run dev

Code Standards

  • Follow TypeScript best practices with strict typing

  • Write pure functions with immutability where possible

  • Use dependency injection for testability

  • Include comprehensive unit tests (AAA pattern)

  • Document public APIs and complex logic

License

This project is licensed under the MIT License.

Acknowledgements

References

Changelog

See CHANGELOG.md for version history.

Note: This server is designed for use with MCP clients (e.g., OpenClaw). It provides AI agents with EPUB reading capabilities while maintaining session isolation and resource management.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/donghch/mcp-epub-reader'

If you have feedback or need assistance with the MCP directory API, please join our Discord server