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
- 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 deliveryinvoice_risk— late-payment risk predictionpayment_reconcile— match Stripe/PayPal/bank payments to invoicescashflow_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.