InvoiceFlow MCP

AI-powered invoice automation for the Model Context Protocol

![License: MIT](LICENSE) ![TypeScript](https://www.typescriptlang.org/) ![MCP](https://modelcontextprotocol.io/)

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

Search for InvoiceFlow MCP on mcpize.com
Click Install — Free tools work immediately; unlock Pro with a €12 lifetime license (see Pro License)
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.

invoiceflow-mcp