InvoiceFlow MCP

AI-powered invoice automation for the Model Context Protocol

InvoiceFlow creates professional PDF invoices, predicts late payment risk using AI, auto-sends reminders, matches incoming payments to invoices, and tracks your cash flow -- all through the MCP protocol.

---

Features

- Professional PDF invoices with line items, tax, discounts, multi-currency (10 currencies)
- AI risk prediction (0-100) based on invoice amount, client history, due date, reminder history
- Smart reminders with escalation based on risk level
- Payment reconciliation matching incoming payments to invoices by amount + payer email (platform-agnostic — works with manually-entered or webhook-provided payment data)
- Cash flow reporting with collection rate, projected income, client breakdown
- Client management with automatic payment history tracking
- Sequential invoice numbers (INV-2026-0001, INV-2026-0002, ...)
- 10 MCP tools + 4 MCP resources covering the full invoicing lifecycle

---

Quick Start

Install from MCPize Marketplace

1. Search for InvoiceFlow MCP on mcpize.com
2. Click Install — Free tools work immediately; unlock Pro with a €12 lifetime license (see Pro License)
3. Tools and resources are automatically available in any MCP-compatible client

Build from Source

git clone https://github.com/enzoemir1/invoiceflow-mcp.git
cd invoiceflow-mcp
npm ci
npm run build

Add to your MCP client config:

{
  "mcpServers": {
    "invoiceflow": {
      "command": "node",
      "args": ["path/to/invoiceflow-mcp/dist/index.js"]
    }
  }
}

---

Tools

invoice_demo_seed

Seed a realistic demo dataset — 8 clients across 5 archetypes (on-time, late-payer, high-value, new, chronic-late) and 25-45 invoices over the last 6 months — so every tool returns meaningful output without any credentials. Safe to call multiple times; each call appends a fresh batch with unique UUIDs. Returns counts plus sample_invoice_ids.

client_manage

Create a new client. Required before creating invoices.

invoice_create

Create an invoice with line items. Auto-calculates subtotal, tax, discounts, and total. Generates sequential invoice numbers (INV-YYYY-NNNN).

invoice_send

Send an invoice PDF via email (requires SENDGRID_API_KEY). Updates status to "sent".

invoice_list

Filter invoices by status, client, amount range, date range, or overdue status. Supports pagination.

invoice_mark_paid

Mark an invoice as paid (full or partial). Updates client payment history automatically.

invoice_remind

Send a payment reminder. Increments reminder count. Supports custom messages.

invoice_risk

AI-powered late payment risk prediction (0-100). Returns risk level, factor breakdown, recommended action, next reminder date.

cashflow_report

Generate cash flow summary: total invoiced, collected, outstanding, overdue, collection rate, 30-day projection.

payment_reconcile

Match incoming payment to invoice by amount and payer email. Auto-marks as paid.

---

Resources

| Resource | Description |
|----------|-------------|
| invoices://pending | All unpaid invoices |
| invoices://overdue | Invoices past due date |
| invoices://stats | Monthly cash flow summary |
| clients://list | All clients with payment history |

---

Risk Prediction Engine

Scores invoices 0-100 using 4 weighted factors:

| Factor | Weight | What It Measures |
|--------|--------|-----------------|
| Invoice Amount | 20% | Higher amounts = higher risk |
| Client History | 35% | Pay rate, late payments, avg days |
| Due Date | 30% | Days until/past due |
| Reminders | 15% | Reminders already sent |

Risk Levels: Low (0-30), Medium (31-60), High (61-100)

---

Configuration

Copy .env.example to .env and set the variables you need:

cp .env.example .env

| Variable | Required | Description |
|----------|----------|-------------|
| SENDGRID_API_KEY | For email sending | Send invoices and reminders via SendGrid |

> SendGrid is optional. InvoiceFlow works fully offline for invoice creation, risk scoring, cash flow reporting, and reconciliation. Add SendGrid when you want outbound email delivery.

Roadmap: Stripe & PayPal live sync

The payment_reconcile tool currently matches amounts you provide (from a CSV, a webhook, or manual entry) against stored invoices. Direct Stripe and PayPal API integration with webhook listeners is planned for v2.0 — see issues for progress.

Usage Examples

Create a client and invoice

> Create a client "Acme Corp" with email billing@acme.com
✓ Client created: Acme Corp (id: 3f2a...)
> Create an invoice for Acme Corp: 10 hours consulting at $150/hr, 20% tax
✓ Invoice INV-2026-0001 created

  Subtotal: $1,500.00 | Tax: $300.00 | Total: $1,800.00

Assess payment risk

> What's the risk score for invoice INV-2026-0001?
Risk Score: 42/100 (Medium)

  - Invoice Amount: 25 (moderate amount)

  - Client History: 50 (new client)

  - Due Date: 15 (due in 28 days)

  - Reminders: 10 (none sent)

Recommended: Send an early reminder with a polite tone.

Generate cash flow report

> Show me the cash flow report
April 2026:

  Total Invoiced: $12,400.00

  Collected: $8,200.00 (66.1%)

  Outstanding: $4,200.00

  Overdue: $1,800.00

  Projected (30d): $2,400.00

Supported Currencies

USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR

---

Pricing

| Tier | Price | Tools | Features |
|------|-------|-------|----------|
| Free | €0 | invoice_demo_seed, client_manage, invoice_create, invoice_list, invoice_mark_paid, invoice_remind | PDF invoices, multi-currency, client management, manual reminders |
| Pro | €12 lifetime | + invoice_send, invoice_risk, payment_reconcile, cashflow_report | AI risk scoring, SendGrid delivery, payment reconciliation, cash flow reporting |

One-time €12 lifetime license (3 machines) — no subscription. See Pro License below to buy and activate.

---

Development

npm run dev        # Hot reload
npm run build      # Production build
npm test           # Run tests
npm run inspect    # MCP Inspector

Testing

Tests cover the core business logic:

- Storage — CRUD operations, filtering, sequential invoice numbers
- Risk Model — AI scoring engine with 4 weighted factors, risk classification
- Cash Flow — Report generation, collection rates, projections, client breakdown

npm test           # Run all tests
npx vitest --watch # Watch mode

Pro License

InvoiceFlow ships in Free mode — invoice_demo_seed, client_manage, invoice_create, invoice_list, invoice_mark_paid, and invoice_remind are open. The following tools require a Pro license:

- invoice_send — generate PDF + SendGrid email delivery
- invoice_risk — late-payment risk prediction
- payment_reconcile — match Stripe/PayPal/bank payments to invoices
- cashflow_report — portfolio-wide cash flow + 30-day projection

Buy a Pro License (€12, lifetime, 3 machines): https://automatiabcn.lemonsqueezy.com/buy/2d439c05-f463-4137-8883-950e8ee1112d

Or get the Indie MCP Stack Bundle (€69, all 4 servers).

export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE

Or in your MCP client config:

{
  "mcpServers": {
    "invoiceflow-mcp": {
      "command": "npx",
      "args": ["-y", "invoiceflow-mcp-server"],
      "env": { "LEMONSQUEEZY_LICENSE_KEY": "YOUR-KEY-HERE" }
    }
  }
}

Validation is cached locally for 24 h — fully offline-capable after first run.

---

License

MIT License. See LICENSE for details.

Built by Automatia BCN.