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

bash

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

Add to your MCP client config:

config.json

{
  "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:

bash

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

Code

> 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

Code

> 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

Code

> 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

Terminal

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

Terminal

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).

server.ts

export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE

Or in your MCP client config:

config.json

{
  "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.