Agent Invoice

Invoicing, billing, and payment tracking for autonomous AI agents

MCP server + CLI + REST API for autonomous agents to generate, track, and manage invoices.

Built for the agentic economy — by Nyx Builds.

MCP Server Setup

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agent-invoice": {
      "command": "uvx",
      "args": ["agent-invoice", "serve"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "agent-invoice": {
      "command": "uvx",
      "args": ["agent-invoice", "serve"]
    }
  }
}

Any MCP host: command: uvx, args: ["agent-invoice", "serve"]

Why?

Agents do work. Agents need to get paid. But there's no standard way for an autonomous agent to:

Generate an invoice for completed work
Track payment status across clients
Maintain a ledger of earnings
Integrate billing into their workflow via MCP
Bill in multiple currencies with tax calculations
Set up recurring invoices for retainer clients
Chase overdue payments automatically
Issue credit notes and refunds
Generate client statements

Agent Invoice fixes this. It's a self-contained billing system designed for AI agents.

Features

📄 Invoice Generation — Create professional invoices with line items, due dates, and client info
💰 Tax Calculation — Per-line-item and invoice-level tax rates with automatic computation
💱 Multi-Currency — 15+ currencies (USD, EUR, GBP, JPY, etc.) with proper symbols and decimal handling
💳 Partial Payments — Record multiple payments against an invoice, track remaining balance
📝 Credit Notes — Issue credits/refunds, apply them to invoices, track applications
📊 Client Statements — Period financial statements with opening/closing balances
🔄 Recurring Invoices — Set up weekly, biweekly, monthly, quarterly, or yearly billing templates
⏰ Dunning Automation — Automated overdue reminders with configurable escalation levels
🔍 Invoice Search — Search by text, date range, amount range, status, client, currency
📋 Invoice Templates — Built-in and custom templates for quick invoice creation
📑 Estimates & Quotes — Create quotes, send, accept/decline, and convert to invoices
📊 A/R Aging Reports — Track outstanding receivables by aging buckets (0-30, 31-60, 61-90, 90+ days)
📈 Revenue Analytics — Monthly revenue trends, collection rate, avg days to pay, top clients
🏷️ Custom Numbering — Configurable invoice numbering (prefix, separator, digits)
📊 Payment Tracking — Monitor which invoices are pending, paid, partially paid, or overdue
📒 Earnings Ledger — Running total of all income, tax, and discounts across invoices
📤 Export — Export invoices as PDF, JSON, or Markdown
🤖 Usage Metering (v0.8.0) — Track AI/API consumption (tokens, cost, provider, model) and bill clients based on actual usage
💸 Usage-Based Billing (v0.8.0) — Aggregate usage events into invoices with per-provider/model line items and optional markup
📊 Cost Analytics (v0.9.0) — Cost trends, projections, anomaly detection, model efficiency scoring, and provider comparison
💰 Late Fee Engine (v1.1.0) — Configurable late payment penalties (fixed, percentage, compound) with grace periods, recurring accrual, fee caps, waive/forgive, and analytics
🏷️ Promo Codes & Discounts (v1.2.0) — Promotional codes (percentage/fixed) with usage limits, expiry, client/currency restrictions, minimum spend; tiered volume discounts; early payment terms (2/10 net 30); redemption analytics
🔌 MCP Server — 128 tools for full billing integration via Model Context Protocol
🌐 REST API — Full HTTP API with FastAPI for web integration
💻 CLI — Command-line interface with 40+ commands for direct use or scripting
💾 JSON Storage — Simple file-based storage, no database required

Quick Start

CLI Usage

# Create a client (with EUR as default billing currency)
agent-invoice client add "Acme Corp" --email billing@acme.com --currency EUR

# Create an invoice with tax
agent-invoice create \
  --client "Acme Corp" \
  --item "Code review,40,150.00,8.5" \
  --item "Bug fixes,10,200.00" \
  --tax-rate 8.5 \
  --due 30

# Apply a discount
agent-invoice discount INV-0001 50.00

# Record a partial payment
agent-invoice payment add INV-0001 --amount 500.00 --method bank_transfer

# List all invoices in EUR
agent-invoice list --currency EUR

# Search invoices
agent-invoice list --search "consulting" --min-amount 500.0
agent-invoice list --status overdue
agent-invoice list --date-from 2026-01-01 --date-to 2026-06-30

# Mark an invoice as paid
agent-invoice pay INV-0001

# Show earnings summary
agent-invoice earnings

# Export to PDF
agent-invoice export INV-0001 --format pdf --company-name "My Agent Co"

# --- Recurring invoices ---
agent-invoice recurring create \
  --client "Acme Corp" \
  --item "Retainer,1,500.00" \
  --frequency monthly

agent-invoice recurring generate REC-ABC123
agent-invoice recurring process    # Generate all due

# --- Credit notes ---
agent-invoice credit create --client "Acme Corp" --amount 250.00 --reason "overpayment"
agent-invoice credit apply CN-ABC123 --invoice INV-0001
agent-invoice credit list --status open

# --- Client statements ---
agent-invoice statement "Acme Corp" 2026-01-01 2026-06-30

# --- Estimates & Quotes ---
agent-invoice estimate create "Acme Corp" --description "Website redesign" --quantity 1 --price 5000.00 --terms "Net 30"
agent-invoice estimate create "Acme Corp" --description "Monthly support" --price 2000.00 --expiry 15 --tax-rate 8.5
agent-invoice estimate list --status draft
agent-invoice estimate show EST-ABC123
agent-invoice estimate send EST-ABC123
agent-invoice estimate accept EST-ABC123
agent-invoice estimate convert EST-ABC123 --due-days 30

# --- A/R Aging Report ---
agent-invoice ar-aging
agent-invoice ar-aging --currency USD

# --- Revenue Analytics ---
agent-invoice revenue
agent-invoice revenue --months 12 --currency USD

# --- Dunning (overdue reminders) ---
agent-invoice dunning config
agent-invoice dunning send INV-0001
agent-invoice dunning process    # Auto-send reminders for all overdue

# --- Templates ---
agent-invoice template list
agent-invoice template use TPL-HOURLY --client "Acme Corp"

# --- Numbering ---
agent-invoice numbering set --prefix BIL --separator / --digits 3

# List supported currencies
agent-invoice currencies

MCP Server

Start the MCP server for integration with any MCP-compatible agent:

agent-invoice serve

The server exposes 55 tools:

Invoices & Line Items:

create_invoice — Generate a new invoice (with tax, currency, discounts)
list_invoices — List invoices with filtering (status, client, currency)
get_invoice — Get details of a specific invoice
mark_paid / mark_sent / cancel_invoice — Status management
apply_discount — Apply a discount
add_line_item / remove_line_item — Edit draft invoices
search_invoices — Search by text, date range, amount range
export_invoice — Export as markdown, JSON, or PDF

Payments:

record_payment — Record a payment (full or partial)
list_payments / remove_payment — Payment management

Clients:

add_client — Register a client (with default currency)
update_client / list_clients — Client management
client_statement — Generate period financial statements

Credit Notes:

create_credit_note — Issue a credit/refund
list_credit_notes / get_credit_note — View credit notes
apply_credit_note — Apply credit to an invoice
void_credit_note / remove_credit_note — Void or delete

Recurring:

create_recurring — Create a recurring invoice template
list_recurring / generate_from_recurring
pause_recurring / resume_recurring / process_due_recurring

Templates:

list_templates / get_template / create_template
create_invoice_from_template / remove_template

Dunning:

get_dunning_config / update_dunning_config
send_dunning_reminder — Send a reminder for an overdue invoice
process_overdue_dunning — Auto-process all overdue
list_dunning_actions / remove_dunning_action

Config & Utilities:

get_numbering_config / update_numbering_config
earnings_summary / list_currencies

Estimates & Quotes:

create_estimate — Create a quote with line items, tax, discount, and expiry
list_estimates — List quotes with optional status/client filters
get_estimate — Get full details of a specific quote
send_estimate — Mark a quote as sent to the client
accept_estimate / decline_estimate — Client decision tracking
convert_estimate_to_invoice — Convert an accepted quote into an invoice
remove_estimate — Delete a quote (cannot delete converted ones)

Reports & Analytics:

generate_ar_aging_report — A/R aging with per-client bucket breakdown
get_revenue_analytics — Monthly trends, collection rate, days to pay, top clients

REST API

Start the HTTP server:

uvicorn agent_invoice.api:create_app --factory --port 8000

Full CRUD API with endpoints for invoices, payments, clients, credit notes, statements, recurring, templates, dunning, estimates, reports, earnings, and currencies.

# Create a client
curl -X POST http://localhost:8000/clients \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "currency": "USD"}'

# Create an invoice
curl -X POST http://localhost:8000/invoices \
  -H "Content-Type: application/json" \
  -d '{"client": "CLT-...", "items": [{"description": "Work", "quantity": 10, "unit_price": 100}]}'

# Record a payment
curl -X POST http://localhost:8000/invoices/INV-0001/payments \
  -H "Content-Type: application/json" \
  -d '{"amount": 500.00, "method": "bank_transfer"}'

# Create an estimate
curl -X POST http://localhost:8000/estimates \
  -H "Content-Type: application/json" \
  -d '{"client": "CLT-...", "line_items": [{"description": "Project", "quantity": 1, "unit_price": 5000}]}'

# Convert an estimate to invoice
curl -X POST http://localhost:8000/estimates/EST-ABC123/convert?due_days=30

# Get A/R aging report
curl http://localhost:8000/reports/ar-aging?currency=USD

# Get revenue analytics
curl http://localhost:8000/reports/revenue?period_start=2026-01-01&period_end=2026-06-30

Tax Calculation

Agent Invoice supports two levels of tax:

Line-item tax — Set a tax rate on individual items: --item "Consulting,10,200.00,8.5"
Invoice-level tax — Set a default tax rate for items without their own: --tax-rate 8.5

Items with their own tax rate override the invoice-level rate. The grand total is computed as:

Subtotal + Total Tax - Discount = Grand Total

Credit Notes

Issue credits for overpayments, refunds, or billing errors:

# Create a credit note
agent-invoice credit create --client "Acme Corp" --amount 250.00 --reason "overpayment"

# Apply to an invoice (reduces balance)
agent-invoice credit apply CN-ABC123 --invoice INV-0001

# Apply partial amount
agent-invoice credit apply CN-ABC123 --invoice INV-0001 --amount 100.00

# Void a credit note (only if unapplied)
agent-invoice credit void CN-ABC123

Client Statements

Generate financial statements showing all activity for a period:

agent-invoice statement "Acme Corp" 2026-01-01 2026-06-30

Shows opening balance, period invoices, payments, credit notes, and closing balance.

Dunning (Overdue Management)

Automated escalation reminders for overdue invoices:

# Configure dunning thresholds (days after due date)
agent-invoice dunning config --first 7 --second 14 --final 30

# Send a reminder for a specific invoice
agent-invoice dunning send INV-0001

# Auto-process all overdue invoices (run daily via cron)
agent-invoice dunning process

Multi-Currency

Set a default currency per client, or override per invoice:

# Client with EUR default
agent-invoice client add "Berlin GmbH" --currency EUR

# Override to GBP for a specific invoice
agent-invoice create --client "Berlin GmbH" --currency GBP --item "Work,100.00"

Supported currencies: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, KRW, MXN, SGD, SEK, NZD

Invoice Search

Find invoices by text, amount, or date:

# Text search (matches ID, client name, notes, line item descriptions)
agent-invoice list --search "consulting"

# Amount range
agent-invoice list --min-amount 500.0 --max-amount 5000.0

# Date range
agent-invoice list --date-from 2026-01-01 --date-to 2026-06-30

# Combined filters
agent-invoice list --search "API" --status overdue --min-amount 100.0

Estimates & Quotes

Send quotes before work begins, then convert accepted quotes into invoices:

# Create an estimate with tax and expiry
agent-invoice estimate create "Acme Corp" \
  --description "Website redesign" \
  --quantity 1 \
  --price 5000.00 \
  --tax-rate 8.5 \
  --expiry 30 \
  --terms "Net 30"

# Send the quote to the client
agent-invoice estimate send EST-ABC123

# Client accepts
agent-invoice estimate accept EST-ABC123

# Convert to a real invoice
agent-invoice estimate convert EST-ABC123 --due-days 30

# List all estimates by status
agent-invoice estimate list --status accepted

Estimates have a full lifecycle: draft → sent → accepted/declined → converted. Expired quotes are auto-detected. Converted estimates link back to the invoice they became.

A/R Aging Reports

Track outstanding receivables grouped by how long they've been overdue:

# Full aging report
agent-invoice ar-aging

# Filter by currency
agent-invoice ar-aging --currency USD

Groups outstanding balances into standard aging buckets: 0-30, 31-60, 61-90, 90+ days. Shows per-client breakdown with invoice-level detail (days overdue, amount remaining).

Revenue Analytics

Analyze revenue trends over time:

# Last 6 months (default)
agent-invoice revenue

# Last 12 months
agent-invoice revenue --months 12

Shows monthly invoicing vs. collection trends, overall collection rate (%), average days to pay, fastest/slowest payments, and top clients by revenue.

Installation

pip install agent-invoice

Or with uv:

uv pip install agent-invoice

Architecture

agent-invoice/
├── src/agent_invoice/
│   ├── __init__.py
│   ├── models.py       # Pydantic models (Invoice, Client, CreditNote, Estimate, ARAging, RevenueAnalytics, etc.)
│   ├── store.py        # JSON file storage with numbering config
│   ├── service.py      # Business logic layer (50+ methods)
│   ├── cli.py          # Click CLI with 40+ commands
│   ├── mcp_server.py   # MCP server with 101 tools
│   ├── api.py          # FastAPI REST API
│   └── pdf.py          # PDF export with reportlab
├── tests/              # 413 tests (models, store, service, CLI, API, MCP, estimates, reports)
└── data/               # Default storage location

Data Storage

Invoices, clients, recurring templates, credit notes, dunning actions, and templates are stored as JSON files in ~/.agent-invoice/ by default. Set the AGENT_INVOICE_DIR environment variable to customize the location.

License

MIT

Changelog

v1.2.0 — Discount & Promotion Engine

Promo codes, tiered volume discounts, early payment terms, and redemption analytics — the complete discount layer for agentic billing.

Every billing platform needs promotional discounts to drive conversions, volume-based pricing for B2B, and early payment incentives for cash flow. Now agent-invoice does too.

Promo Codes: Redeemable codes with percentage or fixed-amount discounts
- Usage limits: global redemption cap and per-client cap
- Validity window: start date, expiry date
- Restrictions: minimum spend, client whitelist, currency whitelist, max discount cap
- Lifecycle: active → paused → expired/exhausted (auto-transitions)
- Case-insensitive code lookup with auto-normalization
Tiered Volume Discounts: Subtotal-based discount schedules
- Multiple tiers (e.g., Bronze ≥$100 = 5%, Silver ≥$500 = 10%, Gold ≥$1000 = 15%)
- Best qualifying tier automatically selected
- Percentage or fixed-amount per tier with custom labels
Early Payment Discounts: "2/10 net 30" terms attached to invoices
- Configurable discount percentage and payment window
- Terms travel with the invoice (stored in notes)
- Real-time eligibility calculation with days remaining
Discount Redemption Tracking: Every discount application recorded
- Source type (promo, volume, early_payment, manual)
- Original vs. final subtotal, client, currency
Discount Analytics Dashboard: Comprehensive summary
- Total discount given, redemption count, avg per redemption
- Breakdowns by source type, top promo codes, discounts by client
- Revenue impact percentage (discount / (discount + collected))
15 new MCP tools (128 total), 21 new REST API endpoints, 87 new tests (791 total, all passing)

v1.1.0 — Late Fee Engine

Automated late payment penalties for overdue invoices — configurable policies with fixed, percentage, or compound fees.

Every major billing platform (Stripe, QuickBooks, FreshBooks, Xero) supports late fees. Now agent-invoice does too — fully integrated with the existing dunning (reminder) system.

Late Fee Policies: Configurable rules governing how penalties are applied
- Fee types: fixed ($25 flat), percentage (1.5% of outstanding), or compound ($25 + 1.5%)
- Frequency: one-time, daily, weekly, or monthly accrual
- Grace period (configurable days before fees start)
- Maximum total fees cap (safety valve per invoice)
- Minimum outstanding amount threshold
- Exempt invoice statuses (draft, cancelled)
Automatic Application: apply_late_fee for single invoices, process_overdue_late_fees for batch processing
Waive & Forgive: Waive individual late fees with reason tracking
Late Fee Analytics: Comprehensive summary dashboard — total charged/pending/paid/waived, breakdowns by policy and client, top late payers
Multi-currency: Fees charged in invoice's native currency
Integration: Coexists with dunning — reminders and penalties work independently
12 new MCP tools (113 total), 14 new REST API endpoints, 7 new CLI commands
62 new tests (704 total, all passing)

v1.0.0 — Rate Cards & Subscriptions (Recurring Billing)

The first MCP server to unify usage metering → automatic cost calculation → subscription billing → invoicing.

Rate Cards: Define per-token pricing for any provider+model (OpenAI, Anthropic, etc.). Record usage with just tokens — the rate card calculates the cost automatically. No manual cost entry.
- Per-million-token rates: input, output, cache-read, cache-write
- Per-request flat surcharge support
- Multiple rate cards (production, enterprise, dev) with activate/deactivate
Subscriptions: Full recurring billing lifecycle — plans, trial periods, active/past-due/canceled/paused states, automatic invoice generation per billing cycle.
- Plan catalogs with tiered pricing (daily/weekly/monthly/quarterly/yearly)
- Trial support with configurable duration
- Pause/resume, cancel with effective dates
- Auto-invoice generation on cycle renewal
MRR Reporting: Monthly recurring revenue summaries, subscription growth metrics, churn tracking.
Batch Usage Recording: Log hundreds of usage events in a single call with automatic cost calculation via rate cards.
22 new MCP tools (101 total), 66 new tests (642 total, all passing).

v0.9.0 — Usage Analytics & Cost Intelligence

Provider cost analysis, model comparison, cost trends, anomaly detection
5 new analytics MCP tools

v0.8.0 — Usage Metering & Agent Billing

UsageEvent model, usage summaries, aggregate → invoice → mark billed lifecycle
Markup support for reseller margins
6 new metering MCP tools

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Agent Invoice

MCP Server Setup

Why?

Features

Quick Start

CLI Usage

MCP Server

REST API

Tax Calculation

Credit Notes

Client Statements

Dunning (Overdue Management)

Multi-Currency

Invoice Search

Estimates & Quotes

A/R Aging Reports

Revenue Analytics

Installation

Architecture

Data Storage

License

Changelog

v1.2.0 — Discount & Promotion Engine

v1.1.0 — Late Fee Engine

v1.0.0 — Rate Cards & Subscriptions (Recurring Billing)

v0.9.0 — Usage Analytics & Cost Intelligence

v0.8.0 — Usage Metering & Agent Billing

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Agent Invoice

MCP Server Setup

Why?

Features

Quick Start

CLI Usage

MCP Server

REST API

Tax Calculation

Credit Notes

Client Statements

Dunning (Overdue Management)

Multi-Currency

Invoice Search

Estimates & Quotes

A/R Aging Reports

Revenue Analytics

Installation

Architecture

Data Storage

License

Changelog

v1.2.0 — Discount & Promotion Engine

v1.1.0 — Late Fee Engine

v1.0.0 — Rate Cards & Subscriptions (Recurring Billing)

v0.9.0 — Usage Analytics & Cost Intelligence

v0.8.0 — Usage Metering & Agent Billing

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages