mcp-billing

mcp-billing

A Model Context Protocol (MCP) server for invoice management, payment tracking, automated dunning, German tax compliance, and billing analytics.

17 tools | 3 resources | Stripe integration | PDF generation | Multi-language (DE/EN/ES)

Features

• Invoice Management -- Create, send, track, and cancel invoices with auto-generated sequential numbers
• PDF Generation -- Professional, legally compliant invoices and dunning letters (German §14 UStG) via Puppeteer
• 3-Level Dunning -- Automated escalation: Payment Reminder (free) → 1st Reminder (5 EUR fee) → 2nd Reminder (10 EUR fee)
• Tax Compliance -- Kleinunternehmer (§19 UStG), Standard VAT (19%), and Reverse Charge (EU B2B)
• Stripe Integration -- Sync payments from Stripe, auto-match to invoices, create invoices from subscriptions
• Credit Notes -- Issue refunds linked to original invoices with auto-status updates
• Analytics -- MRR/ARR dashboard, revenue forecast, payment success rates, revenue by product
• Configurable Branding -- All company details, colors, and prefixes via environment variables

Quick Start

Prerequisites

• Node.js >= 18
• PostgreSQL database
• Puppeteer (for PDF generation)

Installation

npm install mcp-billing

Database Setup

Run the SQL migration to create the 7 billing tables:

psql -d your_database -f scripts/create-tables.sql

Or use Prisma:

DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" npx prisma db push

Configuration

All configuration via environment variables:

# Required
DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

# Branding (all optional, sensible defaults)
BILLING_BRAND_NAME="MyCompany"
BILLING_CONTACT_NAME="John Doe"
BILLING_CONTACT_EMAIL="[e-mail]"
BILLING_WEBSITE_URL="mycompany.com"
BILLING_IBAN="DE89 3704 0044 0532 0130 00"
BILLING_BIC="COBADEFFXXX"
BILLING_INVOICE_PREFIX="INV"          # Default: INV
BILLING_CREDIT_NOTE_PREFIX="CN"       # Default: CN
BILLING_OUTPUT_DIR="./output/invoices" # PDF output directory
BILLING_PAYMENT_TERMS_DAYS="14"       # Default: 14
BILLING_CURRENCY="EUR"                # Default: EUR
BILLING_ACCENT_COLOR="#2563EB"        # Brand color for PDFs

# Product catalog (optional, for subscription-based invoicing)
BILLING_PRODUCTS='{"pro": {"cents": 9900, "label": "Pro Plan"}, "enterprise": {"cents": 29900, "label": "Enterprise Plan"}}'

Running

# Stdio mode (for MCP clients like Claude Desktop)
npx mcp-billing

# HTTP mode (persistent microservice)
MCP_HTTP=1 MCP_PORT=4002 npx mcp-billing

MCP Client Configuration

{
  "mcpServers": {
    "billing": {
      "command": "npx",
      "args": ["mcp-billing"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb",
        "BILLING_BRAND_NAME": "MyCompany",
        "BILLING_INVOICE_PREFIX": "INV"
      }
    }
  }
}

Tools (17)

Invoice Management (6)

Tool	Description
billing_create_invoice	Create from Stripe subscription or manually with company + line items
billing_get_invoice	Lookup by ID or invoice number, returns full details with line items
billing_list_invoices	Filter by status, company, date range, or overdue flag
billing_send_invoice	Mark invoice as sent
billing_mark_paid	Record manual payment (bank transfer, etc.)
billing_cancel_invoice	Cancel with optional reason

PDF Generation (2)

Tool	Description
billing_generate_invoice_pdf	Professional PDF with configurable branding. Supports DE/EN/ES
billing_generate_reminder_pdf	Dunning PDF with original invoice reference and fees

Payments (2)

Tool	Description
billing_sync_payments	Sync from Stripe, auto-match to invoices
billing_list_payments	Payment history with filters

Analytics (2)

Tool	Description
billing_dashboard	MRR, ARR, outstanding/overdue amounts, payment success rate
billing_revenue_forecast	Project revenue forward N months based on churn rate

Dunning (2)

Tool	Description
billing_check_overdue	Find overdue invoices, auto-create escalating reminders
billing_send_reminder	Mark reminder as sent

Tax (1)

Tool	Description
billing_tax_report	Netto/USt/Brutto breakdown by period (month/quarter/year)

Credit Notes (1)

Tool	Description
billing_create_credit_note	Issue refund linked to original invoice

Configuration (1)

Tool	Description
billing_set_tax_config	Set tax mode globally or per company

Resources (3)

URI	Description
billing://dashboard	Live billing dashboard (JSON)
billing://overdue	Current overdue invoices (JSON)
billing://tax-config	Tax configuration (JSON)

Workflows

Monthly Invoicing

• billing_create_invoice for each active subscription
• billing_generate_invoice_pdf for each invoice
• billing_send_invoice to mark as sent

Payment Reconciliation

• billing_sync_payments to pull from Stripe
• billing_list_payments to verify
• billing_mark_paid for manual payments (bank transfers)

Dunning Process

• billing_check_overdue (run daily/weekly)
• billing_generate_reminder_pdf for new reminders
• billing_send_reminder to mark as sent

Tax Reporting

• billing_tax_report with period type
• Review Netto/USt/Brutto breakdown
• Export for tax advisor

Database Schema

7 tables with proper indexes:

• billing_sequences -- Invoice number sequences
• billing_tax_configs -- Tax configuration (global + per-company)
• billing_invoices -- Invoices with full company and tax details
• billing_invoice_items -- Line items per invoice
• billing_payments -- Payment records (Stripe + manual)
• billing_reminders -- Dunning reminders (3 levels)
• billing_credit_notes -- Credit notes / refunds

All monetary values are stored in cents (19900 = 199.00 EUR).

Transport Modes

Mode	Flag	Use Case
Stdio	(default)	Claude Desktop, MCP clients via subprocess
HTTP	--http or MCP_HTTP=1	Persistent microservice, agent fleets

HTTP mode includes:

• Health check endpoint (/health)
• Session management with auto-cleanup (30min TTL)
• CORS support
• Graceful shutdown

Tax Modes

Mode	VAT	Use Case
kleinunternehmer	0%	German small business (§19 UStG)
standard	19%	Regular German VAT
reverse_charge	0%	EU B2B (§13b UStG)

License

MIT