Paddle MCP Server: Catalog, Billing, Subscriptions, Reports

Overview

The Paddle MCP Server is an integration-focused service that helps developers connect their applications to Paddle for product catalog management, billing workflows, subscription lifecycle handling, and finance reporting. It centralizes Paddle-related logic into a single API and background-worker process so your application can rely on a predictable, auditable interface instead of directly handling Paddle webhooks and API nuances.

This server is useful when you need to programmatically synchronize product metadata, validate and reconcile invoices, automate subscription events, or produce exportable reports for accounting. It also provides a place to store and expose normalized data models (catalog items, plans, invoices, subscriptions) that different parts of your system can consume.

Features

• Product catalog syncing and local catalog store
• Billing operations: invoices, payments, refunds reconciliation
• Subscription management: create, update, cancel, change plans
• Report generation: CSV/JSON exports for finance and analytics
• Webhook handling to process Paddle events reliably
• Background jobs and retry handling for external API calls
• Optional Docker and database support for production-ready deployment

Installation / Configuration

Prerequisites:

• Node.js (LTS) or container runtime (Docker)
• A relational database (Postgres is recommended)
• Paddle account credentials (vendor ID / auth code / public key)

Clone and install:

git clone https://github.com/PaddleHQ/paddle-mcp-server.git
cd paddle-mcp-server
npm install

Copy and edit environment variables (example):

cp .env.example .env
# Edit .env to set:
# PADDLE_VENDOR_ID
# PADDLE_VENDOR_AUTH_CODE
# PADDLE_PUBLIC_KEY
# DATABASE_URL (postgres://user:pass@host:port/dbname)
# PORT (optional)

Run database migrations (example using a typical migration tool):

npm run migrate

Start the server locally:

npm start
# or for development
npm run dev

Docker Compose example:

version: "3.8"
services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: paddle
      POSTGRES_USER: paddle
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data
  mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://paddle:secret@db:5432/paddle
      PADDLE_VENDOR_ID: "your-vendor-id"
      PADDLE_VENDOR_AUTH_CODE: "your-auth-code"
    depends_on:
      - db
volumes:
  pgdata:

Available Resources

The server exposes HTTP endpoints and background workers. Typical endpoints you can expect (paths may vary by version):

Other resources:

• Webhook processor that validates Paddle signatures and enqueues jobs
• Admin endpoints for manual reconciliation and retrying failed jobs
• Export utilities to produce CSV/JSON reports for accounting

Example: fetch catalog with curl

curl -H "Authorization: Bearer <API_KEY>" http://localhost:3000/api/catalog

Example: trigger a catalog sync

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  http://localhost:3000/api/catalog/sync

Use Cases

• Sync product catalog to local datastore

  • Run scheduled sync jobs to keep your application’s product list up to date with Paddle. This enables storefronts and checkout flows to reference consistent SKUs and pricing without calling Paddle on every request.

• Automate subscription lifecycle handling

  • Use the subscriptions API to create subscriptions when a purchase is completed, handle upgrades/downgrades, and perform graceful cancellations. Webhook processing ensures changes initiated on Paddle (e.g., proration, chargebacks) are reflected in your system.

• Billing reconciliation and dispute management

  • Ingest invoice and payment events to reconcile receipts, identify failed payments, and trigger follow-up actions (email retries, account holds). Generate reports for accountants that summarize revenue, refunds, and chargebacks.

• Generate periodic finance reports

  • Export weekly or monthly CSVs with invoice lines, taxes, and customer metadata for ingestion into accounting tools or BI systems.

• Sandbox and testing

  • Run the server locally or in CI to simulate Paddle webhooks and validate integration behavior before deploying changes to production.

Tips for Developers

• Store Paddle public keys and verify webhook signatures to ensure authenticity.
• Use background jobs for long-running operations (report generation, bulk sync) to avoid blocking HTTP requests.
• Secure admin and webhook endpoints using API keys or IP whitelisting.
• Keep a reconciliation job that compares Paddle state with your local store and surfaces discrepancies.

For the full source, issues, and contributions, visit the project repository: https://github.com/PaddleHQ/paddle-mcp-server.