PDFMonkey README

PDFMonkey MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with the PDFMonkey API for generating PDFs from templates.

Features

Template Management: List and inspect PDF templates with detailed information (HTML, CSS, properties)
Document Generation: Create PDFs with async generation and automatic polling
Document Management: List, check status, and delete generated documents
Snippet Support: Access reusable Liquid code snippets
Workspace Info: View workspace details
User & Quota Management: Check account quota, plan information, and user details

Quick Start

Option 1: Docker (Recommended)

bash

# Build locally (a published Docker Hub image is not available yet)
docker build -t pdfmonkey-mcp-server:latest .

Configure in Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

config.json

{
  "mcpServers": {
    "pdfmonkey": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PDFMONKEY_API_KEY=your-api-key-here",
        "pdfmonkey-mcp-server:latest"
      ]
    }
  }
}

See DOCKER-MCP-TOOLKIT.md for Docker MCP Toolkit integration.

Option 2: From npm

Terminal

npm install -g pdfmonkey-mcp-server

config.json

{
  "mcpServers": {
    "pdfmonkey": {
      "command": "pdfmonkey-mcp-server",
      "env": {
        "PDFMONKEY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 3: From Source

bash

git clone https://github.com/pdfmonkey/pdfmonkey-mcp
cd pdfmonkey-mcp
npm install
npm run build

config.json

{
  "mcpServers": {
    "pdfmonkey": {
      "command": "node",
      "args": ["/absolute/path/to/pdfmonkey-mcp-server/dist/index.js"],
      "env": {
        "PDFMONKEY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Get Your API Key

Sign up at dashboard.pdfmonkey.io/register
Get your API key from the dashboard

Available Tools (11 total)

Workspace Operations

list_workspaces - List all accessible workspaces

Template Operations

list_templates - List all PDF templates
get_template - Get template details with full HTML, CSS, and properties

Document Operations

generate_document - Generate PDF with async polling (1.5s intervals, 3min timeout)
get_document_status - Check document status and get download URL
list_documents - List documents with filters (status, template_id, page, updated_since)
delete_document - Delete document permanently

Snippet Operations

list_snippets - List all Liquid code snippets
get_snippet - Get snippet code

User & Quota Operations

get_quota - Get quota and plan information
get_user_info - Get complete account details

Usage Examples

Generate an Invoice

Code

User: Generate a PDF invoice using my invoice template

Claude: I'll help you generate an invoice. First, let me list your templates.
[Uses list_templates tool]
I found your invoice template (ID: abc-123). Now I'll generate the PDF.
[Uses generate_document tool with data]
Your invoice has been generated! Download: https://...

View Template Code

Code

User: Show me the HTML and CSS for template abc-123

Claude: [Uses get_template tool]
Here's the complete template:

### 📝 HTML Template
[Shows full HTML code]

### 🎨 CSS Styles
[Shows full CSS code]

### 📊 Sample Data
[Shows JSON properties]

Check Account Status

Code

User: What's my current quota?

Claude: [Uses get_quota tool]
You have 450 documents available on your Professional plan (monthly).
Share links are enabled.

Development

Build

Terminal

npm run build

Test

Terminal

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

Current test coverage: 80/80 tests passing (~89% overall statements/lines; tools.ts dispatch 100%)

Watch Mode

Terminal

npm run watch

Test Locally

server.ts

export PDFMONKEY_API_KEY="your-api-key"
npm start

Test Docker Image

bash

# Build
docker build -t pdfmonkey-mcp-server:latest .

# Test with real API
docker run -it --rm \
  -e PDFMONKEY_API_KEY="your-key" \
  pdfmonkey-mcp-server:latest

# In another terminal, send test JSON-RPC
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  docker run -i --rm -e PDFMONKEY_API_KEY="your-key" pdfmonkey-mcp-server:latest

Publishing to Docker Hub

Prerequisites

Docker Hub account
Image tested and validated
All tests passing

Steps

bash

# 1. Tag image
docker tag pdfmonkey-mcp-server:latest yourusername/pdfmonkey-mcp-server:1.0.0
docker tag pdfmonkey-mcp-server:latest yourusername/pdfmonkey-mcp-server:latest

# 2. Login to Docker Hub
docker login

# 3. Push images
docker push yourusername/pdfmonkey-mcp-server:1.0.0
docker push yourusername/pdfmonkey-mcp-server:latest

Multi-Architecture Build

Support Mac M1/M2 (ARM64) and Intel (AMD64):

bash

# Create builder
docker buildx create --use --name mcp-builder

# Build and push multi-arch
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourusername/pdfmonkey-mcp-server:1.0.0 \
  -t yourusername/pdfmonkey-mcp-server:latest \
  --push \
  .

GitHub Actions CI/CD

Create .github/workflows/docker-publish.yml:

yaml

name: Docker Build and Publish

on:
  release:
    types: [created]
  push:
    branches: [main]

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install and test
        run: |
          npm ci
          npm test
          npm run build

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            yourusername/pdfmonkey-mcp-server:latest
            yourusername/pdfmonkey-mcp-server:${{ github.ref_name }}

Docker Image Details

Base: Node 18 Alpine
Size: ~236MB
User: Non-root (nodejs:1001)
Security: Read-only filesystem, no hardcoded secrets
Architecture: Multi-arch (AMD64, ARM64)

API Reference

Important Notes

Async Generation: generate_document polls every 1.5 seconds for up to 3 minutes
Download URLs: Expire after 1 hour
Share Links: Permanent URLs for premium users
Rate Limiting: 60 requests/minute

Full API documentation: docs.pdfmonkey.io

Troubleshooting

"PDFMONKEY_API_KEY environment variable is required"

Verify your configuration file includes the API key.

"Invalid API key" or 401 errors

Get a new key from dashboard.pdfmonkey.io.

Document generation timeout

Generation took >3 minutes. Use get_document_status with the document ID to check later.

Docker container exits immediately

Ensure you're using -i (interactive) flag:

Terminal

docker run -i --rm -e PDFMONKEY_API_KEY="key" pdfmonkey-mcp-server:latest

View Docker logs

Terminal

docker logs <container-id>

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass (npm test)
Submit a pull request

Testing

The project has comprehensive test coverage:

Unit tests: 80 tests covering the formatters, API client, and tool/prompt dispatch
Coverage: ~89% overall statements/lines (tools.ts dispatch at 100%)
Mock testing: Full fetch API mocking
Async testing: Polling and timeout scenarios

Run tests:

Terminal

npm test              # All tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Project Structure

Code

pdfmonkey-mcp-server/
├── src/
│   ├── index.ts              # MCP server bootstrap (env, client, stdio)
│   ├── tools.ts              # Tool/prompt definitions + dispatch
│   ├── pdfmonkey-client.ts   # PDFMonkey API client
│   └── formatters.ts         # Output formatters
├── tests/
│   └── unit/
│       ├── formatters.test.ts        # Formatter tests (21)
│       ├── pdfmonkey-client.test.ts  # Client tests (25)
│       └── tools.test.ts             # Tool dispatch tests (34)
├── server.json               # MCP registry manifest
├── Dockerfile                # Multi-stage build
├── package.json
├── tsconfig.json
└── jest.config.js

PDFMonkey MCP Server

Features

Quick Start

Option 1: Docker (Recommended)

Option 2: From npm

Option 3: From Source

Get Your API Key

Available Tools (11 total)

Workspace Operations

Template Operations

Document Operations

Snippet Operations

User & Quota Operations

Usage Examples

Generate an Invoice

View Template Code

Check Account Status

Development

Build

Test

Watch Mode

Test Locally

Test Docker Image

Publishing to Docker Hub

Prerequisites

Steps

Multi-Architecture Build

GitHub Actions CI/CD

Docker Image Details

API Reference

Important Notes

Troubleshooting

"PDFMONKEY_API_KEY environment variable is required"

"Invalid API key" or 401 errors

Document generation timeout

Docker container exits immediately

View Docker logs

Contributing

Testing

Project Structure

License

Resources

Support