# invoiceflow-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/enzoemir1/invoiceflow-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/invoiceflow-mcp

## Description
AI-powered invoice automation. Create invoices, track payments, and manage cash flow.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "invoiceflow-mcp": {
    "url": "https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE"
  }
}
```

## Documentation & README

# InvoiceFlow MCP

**AI-powered invoice automation for the Model Context Protocol**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.29-2A9D8F.svg)](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](https://github.com/enzoemir1/invoiceflow-mcp/blob/HEAD/LICENSE) for details.

Built by [Automatia BCN](https://github.com/enzoemir1).