io.github.enzoemir1/invoiceflow-mcp
AI-powered invoice automation. Create invoices, track payments, and manage cash flow.
Open source Open in the app JSON README (API)
About
AI-powered invoice automation. Create invoices, track payments, and manage cash flow.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- enzoemir1
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.0
- Last push
- 2026-08-20T21:50:47Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:45
- Updated
- 2026-08-29 03:02:45
- Origin id
io.github.enzoemir1/invoiceflow-mcp
README
# InvoiceFlow MCP
**AI-powered invoice automation for the Model Context Protocol**
[](LICENSE)
[](https://www.typescriptlang.org/)
[](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
1. Search for **InvoiceFlow MCP** on [mcpize.com](https://mcpize.com)
2. Click **Install** — Free tools work immediately; unlock Pro with a €12 lifetime license (see [Pro License](#pro-license))
3. 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:
```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](https://github.com/enzoemir1/invoiceflow-mcp/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](#pro-license)** below to buy and activate.
---
## Development
```bash
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
```bash
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](https://automatiabcn.lemonsqueezy.com/buy/55e932fd-8319-47f0-8e95-0b86a29f2617)** (€69, all 4 servers).
```bash
export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE
```
Or in your MCP client 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](LICENSE) for details.
Built by [Automatia BCN](https://github.com/enzoemir1).