io.github.enzoemir1/invoiceflow-mcp

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

Risk Prediction Engine

Scores invoices 0-100 using 4 weighted factors:

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

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

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.