{
  "markdown": "# InvoiceFlow MCP\n\n**AI-powered invoice automation for the Model Context Protocol**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.29-2A9D8F.svg)](https://modelcontextprotocol.io/)\n\nInvoiceFlow 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.\n\n---\n\n## Features\n\n- **Professional PDF invoices** with line items, tax, discounts, multi-currency (10 currencies)\n- **AI risk prediction** (0-100) based on invoice amount, client history, due date, reminder history\n- **Smart reminders** with escalation based on risk level\n- **Payment reconciliation** matching incoming payments to invoices by amount + payer email (platform-agnostic — works with manually-entered or webhook-provided payment data)\n- **Cash flow reporting** with collection rate, projected income, client breakdown\n- **Client management** with automatic payment history tracking\n- **Sequential invoice numbers** (INV-2026-0001, INV-2026-0002, ...)\n- **10 MCP tools** + **4 MCP resources** covering the full invoicing lifecycle\n\n---\n\n## Quick Start\n\n### Install from MCPize Marketplace\n\n1. Search for **InvoiceFlow MCP** on [mcpize.com](https://mcpize.com)\n2. Click **Install** — Free tools work immediately; unlock Pro with a €12 lifetime license (see [Pro License](#pro-license))\n3. Tools and resources are automatically available in any MCP-compatible client\n\n### Build from Source\n\n```bash\ngit clone https://github.com/enzoemir1/invoiceflow-mcp.git\ncd invoiceflow-mcp\nnpm ci\nnpm run build\n```\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"invoiceflow\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/invoiceflow-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n---\n\n## Tools\n\n### invoice_demo_seed\nSeed 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`.\n\n### client_manage\nCreate a new client. Required before creating invoices.\n\n### invoice_create\nCreate an invoice with line items. Auto-calculates subtotal, tax, discounts, and total. Generates sequential invoice numbers (INV-YYYY-NNNN).\n\n### invoice_send\nSend an invoice PDF via email (requires SENDGRID_API_KEY). Updates status to \"sent\".\n\n### invoice_list\nFilter invoices by status, client, amount range, date range, or overdue status. Supports pagination.\n\n### invoice_mark_paid\nMark an invoice as paid (full or partial). Updates client payment history automatically.\n\n### invoice_remind\nSend a payment reminder. Increments reminder count. Supports custom messages.\n\n### invoice_risk\nAI-powered late payment risk prediction (0-100). Returns risk level, factor breakdown, recommended action, next reminder date.\n\n### cashflow_report\nGenerate cash flow summary: total invoiced, collected, outstanding, overdue, collection rate, 30-day projection.\n\n### payment_reconcile\nMatch incoming payment to invoice by amount and payer email. Auto-marks as paid.\n\n---\n\n## Resources\n\n| Resource | Description |\n|----------|-------------|\n| `invoices://pending` | All unpaid invoices |\n| `invoices://overdue` | Invoices past due date |\n| `invoices://stats` | Monthly cash flow summary |\n| `clients://list` | All clients with payment history |\n\n---\n\n## Risk Prediction Engine\n\nScores invoices 0-100 using 4 weighted factors:\n\n| Factor | Weight | What It Measures |\n|--------|--------|-----------------|\n| Invoice Amount | 20% | Higher amounts = higher risk |\n| Client History | 35% | Pay rate, late payments, avg days |\n| Due Date | 30% | Days until/past due |\n| Reminders | 15% | Reminders already sent |\n\n**Risk Levels:** Low (0-30), Medium (31-60), High (61-100)\n\n---\n\n## Configuration\n\nCopy `.env.example` to `.env` and set the variables you need:\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SENDGRID_API_KEY` | For email sending | Send invoices and reminders via SendGrid |\n\n> 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.\n\n### Roadmap: Stripe & PayPal live sync\n\nThe `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.\n\n## Usage Examples\n\n### Create a client and invoice\n\n```\n> Create a client \"Acme Corp\" with email billing@acme.com\n\n✓ Client created: Acme Corp (id: 3f2a...)\n\n> Create an invoice for Acme Corp: 10 hours consulting at $150/hr, 20% tax\n\n✓ Invoice INV-2026-0001 created\n  Subtotal: $1,500.00 | Tax: $300.00 | Total: $1,800.00\n```\n\n### Assess payment risk\n\n```\n> What's the risk score for invoice INV-2026-0001?\n\nRisk Score: 42/100 (Medium)\n  - Invoice Amount: 25 (moderate amount)\n  - Client History: 50 (new client)\n  - Due Date: 15 (due in 28 days)\n  - Reminders: 10 (none sent)\nRecommended: Send an early reminder with a polite tone.\n```\n\n### Generate cash flow report\n\n```\n> Show me the cash flow report\n\nApril 2026:\n  Total Invoiced: $12,400.00\n  Collected: $8,200.00 (66.1%)\n  Outstanding: $4,200.00\n  Overdue: $1,800.00\n  Projected (30d): $2,400.00\n```\n\n## Supported Currencies\n\nUSD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR\n\n---\n\n## Pricing\n\n| Tier | Price | Tools | Features |\n|------|-------|-------|----------|\n| Free | €0 | `invoice_demo_seed`, `client_manage`, `invoice_create`, `invoice_list`, `invoice_mark_paid`, `invoice_remind` | PDF invoices, multi-currency, client management, manual reminders |\n| Pro | **€12** lifetime | + `invoice_send`, `invoice_risk`, `payment_reconcile`, `cashflow_report` | AI risk scoring, SendGrid delivery, payment reconciliation, cash flow reporting |\n\nOne-time **€12** lifetime license (3 machines) — no subscription. See **[Pro License](#pro-license)** below to buy and activate.\n\n---\n\n## Development\n\n```bash\nnpm run dev        # Hot reload\nnpm run build      # Production build\nnpm test           # Run tests\nnpm run inspect    # MCP Inspector\n```\n\n### Testing\n\nTests cover the core business logic:\n\n- **Storage** — CRUD operations, filtering, sequential invoice numbers\n- **Risk Model** — AI scoring engine with 4 weighted factors, risk classification\n- **Cash Flow** — Report generation, collection rates, projections, client breakdown\n\n```bash\nnpm test           # Run all tests\nnpx vitest --watch # Watch mode\n```\n\n## Pro License\n\nInvoiceFlow 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**:\n\n- `invoice_send` — generate PDF + SendGrid email delivery\n- `invoice_risk` — late-payment risk prediction\n- `payment_reconcile` — match Stripe/PayPal/bank payments to invoices\n- `cashflow_report` — portfolio-wide cash flow + 30-day projection\n\n**Buy a Pro License (€12, lifetime, 3 machines):** https://automatiabcn.lemonsqueezy.com/buy/2d439c05-f463-4137-8883-950e8ee1112d\n\nOr get the **[Indie MCP Stack Bundle](https://automatiabcn.lemonsqueezy.com/buy/55e932fd-8319-47f0-8e95-0b86a29f2617)** (€69, all 4 servers).\n\n```bash\nexport LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE\n```\n\nOr in your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"invoiceflow-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"invoiceflow-mcp-server\"],\n      \"env\": { \"LEMONSQUEEZY_LICENSE_KEY\": \"YOUR-KEY-HERE\" }\n    }\n  }\n}\n```\n\nValidation is cached locally for 24 h — fully offline-capable after first run.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\nBuilt by [Automatia BCN](https://github.com/enzoemir1).\n",
  "bytes": 8213,
  "sha": "6a0e76fb41d9ab935b00f42dfc09d86460315732d6b2ed5156c587f2fc1b3a6d",
  "repo_slug": "enzoemir1/invoiceflow-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_enzoemir1_invoiceflow_mcp_a0ce1b2b/readme"
}