Home · Guides

Credit notes and purchase orders from chat, against your real invoices

Two documents sit either side of an invoice and neither is an invoice. A credit note is what you owe a client when work comes back or you billed twice: it names the invoice it reverses and takes money off it, with the VAT unwound at the rate you charged. A purchase order is what you owe a supplier before they ship: what you want, at what price, by when, with your own details on it. The MCP Billing Docs server writes both against the invoices and clients the MCP Invoice server already holds, on your machine, with no network call anywhere in it.

Install it beside the invoice server

One click, with no JSON. Download invoice.mcpb and billing-docs.mcpb from the bundle catalog and open them in Claude Desktop. They run on the Node runtime Claude Desktop ships with, so your own PATH and node version never come into it.

Or a URL, with nothing installed. /mcp/connect mints a free anonymous token and prints the ready lines:

claude mcp add --transport http invoice      https://mcp.zovo.one/mcp/invoice/t/<token>
claude mcp add --transport http billing-docs https://mcp.zovo.one/mcp/billing-docs/t/<token>

Or from a clone, for a client with no bundle installer. Build once, then point the client at the built file:

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers && npm install
npm run build -w packages/mcp-license -w servers/invoice -w servers/billing-docs

claude mcp add --scope user invoice      -- node /absolute/path/to/mcp-servers/servers/invoice/dist/index.js
claude mcp add --scope user billing-docs -- node /absolute/path/to/mcp-servers/servers/billing-docs/dist/index.js

Claude Desktop, Cursor, Windsurf and Cline take the same two strings as JSON, in claude_desktop_config.json or the client's own MCP config file:

{
  "mcpServers": {
    "invoice": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-servers/servers/invoice/dist/index.js"]
    },
    "billing-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-servers/servers/billing-docs/dist/index.js"]
    }
  }
}

The npm packages are not published yet, so the npx form below returns a 404 today. It is kept because it is what that config becomes the day the publish lands, with nothing else changed; installing these servers when npx does not work yet has the whole picture.

claude mcp add invoice      -- npx -y @theluckystrike/mcp-invoice
claude mcp add billing-docs -- npx -y @theluckystrike/mcp-billing-docs

Both read one data directory and one business profile, so your name, address, VAT id and default currency are set once. Billing Docs holds no copy of the money, VAT or currency code: it imports computeTotals, currencyDecimals and formatMoney from the invoice engine, which is why a credit note and the invoice it reverses agree to the minor unit rather than to the nearest cent.

The measured thing: a single-rate credit note on a mixed-VAT invoice is wrong by 22.6 percent

Take an invoice with two rates on it, which is ordinary the moment printing, food, books or transport sit next to consulting: EUR 1,000.00 of consulting at 23% plus EUR 500.00 of print at 8%, EUR 1,770.00 gross. The client is owed ten percent back, EUR 177.00.

Written as a single-rate credit note, at the headline 23%, that is net EUR 143.90 and VAT EUR 33.10. Split across the rates the invoice actually used, in proportion to each rate's share of the total, it is net EUR 150.00 and VAT EUR 27.00, EUR 23.00 at 23% and EUR 4.00 at 8%.

	Single rate	Split across the invoice's rates
Gross	EUR 177.00	EUR 177.00
Net	EUR 143.90	EUR 150.00
VAT	EUR 33.10	EUR 27.00

The gross is identical. The document the client receives, the amount they are refunded and the payment that follows are the same under both methods, so the counterparty has nothing to query and no later reconciliation surfaces it. The only line that differs is the VAT, by EUR 6.10, which is 22.6 percent of it, and that is the number that goes on a VAT return.

This generalises past VAT: when a wrong answer and a right answer agree on the one figure the counterparty checks, no amount of downstream review finds the error. It has to be right at the point the document is written. credit_note_create with an amount_minor therefore splits the gross across the invoice's own rates and reuses each one, rather than asking you for a rate.

Three ways to credit, and why two of them copy rather than recompute

credit_note_create takes an invoice number and one of three things:

Nothing else: the whole invoice is reversed.
An amount_minor: a gross figure in minor units, split across the invoice's rates as above.
lines: named invoice lines with quantities, for "they returned two of the five".

A whole invoice and a whole line copy the stored numbers instead of recomputing them. The client agreed to the figures the invoice printed, and recomputing a line from a rounded unit price is exactly how a document and the credit note that reverses it come to differ by a cent. Only a partial quantity is recomputed, and then on the invoice's own unit price, tax rate and discount.

Every money field is stored negative, including the unit price, while the quantity stays positive: a line reads 10 x EUR -90.00 = EUR -900.00, which reproduces on a calculator, and summing gross_minor over a period's documents gives the net of what was billed without anybody having to know which rows to flip.

You cannot credit more than the invoice charged

The remaining creditable amount is the invoice total less everything already credited against it, read from this server's own store. Ask for a cent more and it refuses by name, and stores nothing:

at most EUR 1107.00 can still be credited; this credit note is for EUR 1107.01.
A credit note that gives back more than was billed is a refund, not a credit note.
Nothing was stored.

The check and the write are one critical section under both servers' locks, so two processes cannot each see room and both take it. Ten concurrent EUR 200.00 credits against a EUR 1,107.00 invoice store exactly five and refuse exactly five.

The link lives on the credit note rather than on the invoice, deliberately: the invoice engine's record has no credited field, and adding one would mean two servers writing the same record with whichever saved last winning. credit_note_list {invoice: "INV-2026-0001"} is the query, and the create response says so rather than leaving it to be found.

Purchase orders, and receiving them in part

purchase_order_create takes line items, VAT, a currency and an expected delivery date, and purchase_order_text gives you the message to send the supplier. purchase_order_receive marks it received in full or in part, so an order stays open at "3 of 10 delivered" instead of being a yes or a no. Receiving the same order in full twice is refused with the date it was already received on; a receipt dated before the order is refused by name; two currencies on one order is refused before anything is stored.

billing_docs_report is the read that makes the pile useful: credited per currency, on order per currency, and every delivery past its date. There is a chase_deliveries prompt and a billing-docs://open-orders resource for the same question asked from the client's own UI.

Numbering

Ids are CN-YYYY-NNNN and PO-YYYY-NNNN, the same shape as INV-YYYY-NNNN and Q-YYYY-NNNN. A counter that resets every January collides with last January's document, so the year is in the id. The counter is written before the row, so a crash burns an id rather than reusing one, and existing ids are scanned first so a restored store cannot reissue one.

When the invoice is not in the invoice server

Everything above assumes the invoice being credited lives in the MCP Invoice store, because that is what lets the credit copy the invoice's own rates. Sometimes it does not: the invoice went out from a different system, or the credit is standalone and reverses nothing on file. The MCP Credit Note server (mcp-credit-note) covers that case. It opens no sibling store: credit_note_create takes the recipient, a reason, the lines and a currency, and the invoice it credits is a reference string rather than a record it reads. The numbering rule is the same one: drafts carry a CN-DRAFT-YYYY-NNNN id no client sees, the final CN-YYYY-NNNN number is burned only at finalize, and a finalized note cannot be edited or deleted. The line math is round half-up per line then sum, so the printed note reproduces on a calculator. Free is ten finalized notes, lifetime, with drafts, edits, rendering and the totals summary unlimited. It has no hosted endpoint, so it installs from the bundle or a clone. When the invoice IS in the invoice server, stay with the billing-docs route: copying the stored rates is the thing a standalone note cannot do.

Free tier and Pro

Free gives 5 documents a calendar month, credit notes and purchase orders together, counted by issue date. Everything that decides whether the document is correct is on the free tier: full, partial and per-line credit notes, the VAT split, multiple currencies, the over-credit refusal and receiving orders, plus both plain-text exports unmetered. Pro ($19 once, or $39 for the whole collection, lifetime) removes the monthly count and adds both A4 PDFs with your logo and no footer credit, and billing_docs_report. Full detail on the MCP Billing Docs page and the general free versus Pro comparison.

Questions

Why does crediting part of a mixed-VAT invoice at one rate matter if the client is refunded the right amount?

Because only the VAT line is wrong. On an EUR 1,770.00 invoice of consulting at 23% and print at 8%, a EUR 177.00 credit is gross EUR 177.00 either way, so the client's document and the payment are identical and nothing downstream queries it. The VAT differs by EUR 6.10, 22.6 percent of it, and that figure goes on a VAT return. The split has to be right when the document is written.

Can a credit note give back more than the invoice charged?

No. The remaining creditable amount is the invoice total less everything already credited against it, and a request for more is refused by name with nothing stored: a credit note that gives back more than was billed is a refund, not a credit note. The check and the write are one critical section under both locks, so ten concurrent EUR 200.00 credits against EUR 1,107.00 store exactly five.

Does it write to my invoices?

No. The invoice engine's Invoice record has no credited field, and adding one would mean two servers writing the same record with whichever saved last winning. The link lives on the credit note, and credit_note_list {invoice: "INV-2026-0001"} is the query. If a future invoice version carries the field, it is written back too, so the two can never disagree by omission.

Why are credit note amounts stored negative?

So a bookkeeper summing gross_minor over a period's documents gets the net of what was billed without knowing which rows to flip. The unit price is negative and the quantity positive, so a line reads 10 x EUR -90.00 = EUR -900.00 and reproduces on a calculator.

What counts against the 5 free documents a month?

Created credit notes and purchase orders together, counted by issue date, so a document dated in another month is not blocked by this month's count. Reading, listing, receiving an order and both plain-text exports are never metered. The two PDFs and billing_docs_report are Pro.

Do I need the invoice server as well?

For credit notes, yes: they are written against invoices and clients that server holds, and the money and VAT code is imported from it rather than copied. Purchase orders only need the shared business profile, so they work with billing-docs alone, but running both is the intended setup.

All MCP servers and prices · All guides · Buy the bundle $39

Servers used in this guide: MCP Billing Docs · MCP Server for Packing Lists — Packing Slips from Claude