maroun2/pdf-spread-viewer

PDF Spread Viewer MCP Server

A simple MCP (Model Context Protocol) server that converts PDF double-page spreads into single images with black borders, perfect for reviewing book layouts.

Features

• Convert two consecutive PDF pages into one side-by-side image
• Add black borders to simulate book binding/gutter
• High-quality output (200 DPI)
• Simple stdio-based MCP server (no web server needed)
• Returns images directly in MCP responses

Installation

Prerequisites

Make sure you have Python 3.7+ and poppler installed:

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

# Windows
# Download from: https://github.com/oschwartz10612/poppler-windows/releases

Install Python Dependencies

cd ~/projects/pdf-spread-viewer
pip install -r requirements.txt

Or manually:

pip install pdf2image Pillow

Usage

As MCP Server in Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "pdf-spread-viewer": {
      "command": "python3",
      "args": ["/Users/rmi/projects/pdf-spread-viewer/server.py"]
    }
  }
}

Then restart Cursor and use the get_spread tool:

Show me pages 14-15 of embers_final.pdf as a double-page spread

Standalone Script

You can also use it as a standalone script:

python3 server.py

Then send JSON-RPC requests via stdin:

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_spread", "arguments": {"pdf_path": "~/projects/books/dragon-fly/embers_final.pdf", "left_page": 14, "right_page": 15}}}

Tool Parameters

get_spread

Converts two PDF pages into a single side-by-side image.

Parameters:

• pdf_path (string, required): Path to PDF file (supports ~ for home directory)
• left_page (integer, required): Left page number (1-based)
• right_page (integer, required): Right page number (1-based)
• border_width (integer, optional): Border width in pixels (default: 2)

Returns:

• PNG image showing both pages side-by-side with black borders

Example Output

The tool creates images that look like this:

┌──────────────────────────────────────────────┐
│  ┌──────────┐ │ ┌──────────┐                │
│  │ Page 14  │ │ │ Page 15  │                │
│  │  (text)  │ │ │  (image) │                │
│  └──────────┘ │ └──────────┘                │
└──────────────────────────────────────────────┘
     Left page      Right page

The black border in the center simulates the book's gutter/binding.

License

MIT License - feel free to use and modify!

Contributing

This is an open-source project. PRs welcome!

Repository: https://github.com/yourusername/pdf-spread-viewer (update with actual URL)

Troubleshooting

Error: "pdf2image not found"

pip install pdf2image Pillow

Error: "poppler not found"

brew install poppler  # macOS

Error: "PDF file not found"

• Use absolute paths or ~ for home directory
• Check file exists with ls -la path/to/file.pdf