# invbg-mcp

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/unbelievable-digital/Inv.bg-MCP)

Remote MCP server (Claude connector) for the [inv.bg](https://inv.bg) invoicing API (APIv3).
Runs on Cloudflare Workers with Streamable HTTP transport, so it can be added
directly as a **custom connector** in Claude (claude.ai → Settings → Connectors)
or as a remote MCP server in Claude Code / Claude Desktop.

## Tools

### Read

| Tool | Description |
|------|-------------|
| `invbg_list_clients` | List clients with filters (name, EIK/Bulstat, VAT number, EGN, person/company) and pagination |
| `invbg_get_client` | Get a single client by ID |
| `invbg_list_invoices` | List invoices/documents; filter by `client_id`, client name, payment status, type, date range, number |
| `invbg_get_invoices_for_period` | Fetch ALL documents for a period (`days_back` or explicit date range) with auto-pagination; compact summaries incl. `creator` |
| `invbg_get_invoice` | Full document details including line items |
| `invbg_get_invoice_items` | Only the line items (plus currency and total) of a document |
| `invbg_detect_recurring` | Heuristic recurring-billing detection per client+currency: typical amount/day with stability flags, skipped months, unpaid alarms, creators, trend (`increased`/`decreased`/`stable`/`stopped`). Tunable via `months_back`, `min_months`, `amount_tolerance`, `day_tolerance`, `types` |
| `invbg_list_recurring_templates` | Periodic-invoice templates **derived** from documents flagged `issued_from_periodic_invoice` (APIv3 has no native template endpoint): median amount, interval, last/next issue date, active flag |
| `invbg_report_turnover` | Turnover grouped by `client`, `creator` (user), or time (`day`/`week`/`month`/`year`): document count, total, paid, outstanding per currency; credit notes subtracted. Computed from documents — inv.bg's own `/reports/*` endpoints return XLSX only |
| `invbg_report_receivables_aging` | Collections alarm: outstanding balances bucketed by days overdue (not_due/1-30/31-60/61-90/90+) from the due date, per client with per-invoice breakdown and per-currency totals |
| `invbg_report_item_turnover` | Which items/services sold how much: quantity, revenue, document count per item and currency, aggregated from line items (period capped at 300 documents) |
| `invbg_get_invoice_pdf_link` | Shareable l.inv.bg link for one or more documents — recipient views/downloads the PDF without login; valid up to 30 days |
| `invbg_list_payments` | Received/expense payments: amount, date, counterparty, processor, allocation |
| `invbg_list_items` | Item/service catalog with search and tag filtering |
| `invbg_list_bank_accounts` | Bank accounts: alias, bank, IBAN, BIC, currency |
| `invbg_list_bank_transactions` | Imported bank transactions |
| `invbg_get_firm_info` | Firm profile + next free invoice number |
| `invbg_list_comments` | Comments on documents (filter by `entity_id`) |
| `invbg_lookup_company` | Bulgarian commercial register lookup by EIK/Bulstat or name — official name, VAT number, MOL, address |

### Analytics (computed)

| Tool | Description |
|------|-------------|
| `invbg_compare_periods` | MoM / YoY / custom period comparison: totals per currency + per-client movement (new, grown, shrunk, lost clients) |
| `invbg_cashflow_forecast` | Expected monthly income from active recurring clients + overdue collections backlog |
| `invbg_client_health` | Client card: yearly turnover, outstanding, payment behavior (avg days to pay from payment records), recurring status |
| `invbg_report_vat_summary` | Monthly taxable base / VAT / gross per currency (excludes proformas, subtracts credit notes) |
| `invbg_dunning_list` | Collections package: per overdue client a summary + ONE shareable PDF link covering all their overdue documents, ready for reminder emails |

### Write

| Tool | Description |
|------|-------------|
| `invbg_create_invoice_draft` | Creates a **draft** document only (`is_draft: 1`) — review and issue it in the inv.bg UI. Requires a document-level `vat` object (default 20%) |
| `invbg_record_payment` | Records a payment via `/payments/batch`, optionally allocating it to documents (allocation marks them paid). Requires `bank_account_id` (bank/paypal/epay) or `cashbox_id` (cash) |
| `invbg_create_client` | Adds a client. `mol` and `is_reg_vat` are auto-filled — the API requires them despite the spec |
| `invbg_send_document` | Sends documents to an email/phone via inv.bg's secure share link (view/download PDF without login) |
| `invbg_mark_invoice_paid` | Flips a document's payment status (paid/unpaid) directly, without creating a payment record |

Invoice listings are cached in memory for 5 minutes (analytics tools re-use the
same data); any write through the server invalidates the cache.

## Setup

```bash
npm install
cp .dev.vars.example .dev.vars   # then put your real inv.bg API token in it
```

`.dev.vars` and `.env*` are gitignored — secrets never go to git.

## Local development

```bash
npm run dev                       # http://localhost:8787/mcp
npm run inspector                 # MCP Inspector to poke at the tools
```

## Deploy

```bash
npx wrangler deploy
npx wrangler secret put INVBG_API_KEY   # paste your inv.bg token
# optional, recommended — protects the endpoint with a secret URL path:
npx wrangler secret put MCP_AUTH_KEY    # e.g. a long random string
```

## Connect to Claude

The endpoint URL is:

- `https://<worker>.workers.dev/mcp` (no `MCP_AUTH_KEY`), or
- `https://<worker>.workers.dev/mcp/<MCP_AUTH_KEY>` (recommended)

**claude.ai:** Settings → Connectors → Add custom connector → paste the URL.

**Claude Code:**

```bash
claude mcp add --transport http invbg https://<worker>.workers.dev/mcp/<MCP_AUTH_KEY>
```

## Configuration

| Variable | Where | Purpose |
|----------|-------|---------|
| `INVBG_API_KEY` | `.dev.vars` locally, `wrangler secret` in production | inv.bg APIv3 bearer token |
| `MCP_AUTH_KEY` | same | Optional URL path secret; when set, the endpoint moves to `/mcp/<MCP_AUTH_KEY>` |