Skip to content
BranchesTags

Repository files navigation

Flipbook

A lightweight, self-hosted flipbook generator. Upload PowerPoint or PDF files and get beautiful 3D page-curl flipbooks hosted as SEO-optimized webpages, or embeddable in any site via iframe.

See a live example

Features

  • Upload & convert PowerPoint (.pptx, .ppt) and PDF files to interactive flipbooks
  • Import from Google Slides via public share URL
  • 3D page-curl viewer powered by StPageFlip with keyboard navigation, fullscreen, and deep-linking
  • SEO-optimized pages with full slide text rendered as hidden semantic HTML, Open Graph tags, Twitter Cards, JSON-LD structured data, and canonical URLs
  • Embeddable via iframe with a single line of HTML, or host directly as standalone pages
  • Grid view for browsing all slides at a glance
  • Full-text search across slide content
  • MCP server for creating flipbooks from AI agent workflows (Claude Code, Cowork, etc.)
  • Admin dashboard with upload progress tracking, thumbnail previews, and embed code generation
  • Password-protected admin with bcrypt-hashed credentials and session-based auth
  • REST API with required API key authentication
  • Background conversion with real-time progress updates
  • No build tools required — plain Go templates, vanilla JS, no npm/webpack

Tech Stack

Component Technology
Backend Go + chi router
Database MongoDB Atlas
Conversion LibreOffice headless (PPTX/PPT to PDF) + pdftoppm/poppler (PDF to PNG)
Text extraction pdftotext (poppler) for search + SEO
Viewer StPageFlip (vendored, MIT license)
Frontend Server-rendered Go templates, vanilla CSS/JS

Prerequisites

  • Go 1.21+
  • LibreOffice (for PowerPoint conversion)
  • Poppler (provides pdftoppm and pdftotext)
  • MongoDB (Atlas or local)

macOS

brew install poppler
brew install --cask libreoffice

Ubuntu/Debian

sudo apt install poppler-utils libreoffice-impress

Quick Start

# Clone the repo
git clone https://github.com/jonradoff/flipbook.git
cd flipbook

# Copy and edit config
cp config.example.yaml config.dev.yaml
# Edit config.dev.yaml with your MongoDB URI

# Download frontend dependencies
make setup

# Set an admin password
make set-password

# Start the server
make run

The server starts at http://localhost:8080.

Configuration

Flipbook loads configuration from (in order of priority):

  1. Environment variables (prefixed with FLIPBOOK_)
  2. config.dev.yaml (for development, gitignored)
  3. config.yaml (for production)

See config.example.yaml for all available options.

Key settings:

Setting Env Variable Default Description
port FLIPBOOK_PORT 8080 Server port
base_url FLIPBOOK_BASE_URL http://localhost:8080 Public URL
mongo_uri FLIPBOOK_MONGO_URI — MongoDB connection string
session_secret FLIPBOOK_SESSION_SECRET auto-generated Session signing key
api_key FLIPBOOK_API_KEY auto-generated Bearer token for API/MCP auth

Usage

Upload a file

  1. Go to http://localhost:8080/admin
  2. Log in with your admin password
  3. Click Upload and drag in a .pptx, .ppt, or .pdf file
  4. Watch the real-time progress tracker as it converts
  5. Click View Flipbook when ready

Import from Google Slides

  1. In Google Slides, click Share and set access to "Anyone with the link"
  2. Copy the URL
  3. In the admin, switch to the Import from URL tab
  4. Paste the Google Slides URL and click Import & Convert

Viewing flipbooks

Each flipbook gets its own SEO-optimized page at /v/{slug}. These are standalone pages suitable for direct linking, sharing on social media, or indexing by search engines. The page includes:

  • Interactive 3D page-curl viewer
  • Full slide text rendered as hidden semantic HTML for search engine crawlers
  • Open Graph and Twitter Card meta tags with the first slide as the preview image
  • JSON-LD structured data (PresentationDigitalDocument)
  • Canonical URL for proper indexing

Embedding in a webpage

If you prefer to embed a flipbook in an existing page, use the iframe embed code from the admin detail page:

<iframe src="https://your-domain.com/embed/my-presentation"
        width="800" height="600" frameborder="0" allowfullscreen
        style="border:none;border-radius:8px;box-shadow:0 2px 8px rgba(0,0,0,0.1);">
</iframe>

The /embed/{slug} endpoint sets permissive frame headers (X-Frame-Options: ALLOWALL) so it can be embedded on any domain.

API

All API routes require a bearer token. The API key is logged at server startup (auto-generated if not set in config).

# List all flipbooks
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8080/api/flipbooks

# Upload a file
curl -H "Authorization: Bearer YOUR_API_KEY" -X POST -F "file=@deck.pptx" http://localhost:8080/api/flipbooks

# Import from Google Slides
curl -H "Authorization: Bearer YOUR_API_KEY" -X POST \
  -F "url=https://docs.google.com/presentation/d/PRES_ID/edit" \
  http://localhost:8080/api/flipbooks/import

# Get flipbook details
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8080/api/flipbooks/{id}

# Check conversion status (no auth required)
curl http://localhost:8080/api/flipbooks/{id}/status

# Delete a flipbook
curl -H "Authorization: Bearer YOUR_API_KEY" -X DELETE http://localhost:8080/api/flipbooks/{id}

MCP (AI Agent Integration)

The built-in MCP server lets AI agents create and manage flipbooks programmatically. It communicates via JSON-RPC 2.0 over stdin/stdout and authenticates to the API using the same API key from config.

# Start the MCP server (the web server must be running separately)
./flipbook mcp

Configure in Claude Code (~/.claude/settings.json) or any MCP-compatible tool:

{
  "mcpServers": {
    "flipbook": {
      "command": "/path/to/flipbook",
      "args": ["mcp"]
    }
  }
}

Available MCP tools:

Tool Description
list_flipbooks List all flipbooks with status and URLs
create_flipbook Upload a file (base64), wait for conversion
import_google_slides Import from Google Slides URL, wait for conversion
get_flipbook Get flipbook details, page URLs, embed code
get_flipbook_status Check conversion status
delete_flipbook Delete a flipbook and its files

Project Structure

flipbook/
├── main.go                          # Entry point, routing, CLI commands
├── internal/
│   ├── auth/auth.go                 # Password auth + session management
│   ├── config/config.go             # YAML + env config loading
│   ├── converter/                   # PPTX→PDF→PNG pipeline + text extraction
│   ├── database/database.go         # MongoDB operations
│   ├── handlers/                    # HTTP handlers (admin, API, viewer, embed)
│   ├── mcp/server.go                # MCP server (JSON-RPC 2.0 over stdio)
│   ├── models/flipbook.go           # Data models
│   ├── storage/storage.go           # Filesystem storage
│   └── worker/worker.go             # Background conversion queue
├── web/
│   ├── templates/                   # Go HTML templates
│   └── static/                      # CSS, JS, vendored libraries
├── config.example.yaml              # Example configuration
└── data/                            # Runtime data (gitignored)

License

MIT - Copyright (c) 2026 Metavert LLC

About

Embeddable and SEO-optimized presentation viewer built for humans and AI agent workflows

metavert.io/flipbook

Topics

ai-agentsflipbookmcp-serverpdfpowerpointpresentation-slideswebsite

Resources

Readme
MIT license
Activity

Stars

14 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages