Credit note

What credit note MCP server does

The credit note MCP server manages credit notes for an invoice or as standalone documents. A note includes a recipient, reason, currency, and line items with quantities, unit prices in integer minor units, and tax rates. Supported reasons include returned goods, overcharge, discount correction, service issue, and other cases.

New records begin as drafts with identifiers such as CN-DRAFT-YYYY-NNNN. Drafts can be changed or removed when entered incorrectly. Finalization assigns a CN-YYYY-NNNN number and makes the record immutable. After finalization, the document can be read, listed, rendered, and included in summaries, but it cannot be edited or deleted.

The server stores data locally in notes.json and counter.json under ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/credit-note/ when run from source. It does not send credit-note data elsewhere, make network calls, or write rendered documents to disk.

How it works

Use credit_note_create to make a draft, then credit_note_update to replace its details while it remains editable. Updating lines replaces the complete existing line set rather than appending to it. credit_note_finalize assigns the final number and freezes the note.

Amounts use minor units such as cents. Each line’s gross amount is calculated from quantity and unit price, with half-up rounding applied once. Tax is calculated and rounded half-up separately for each line, and the final totals add the already-rounded line values. This makes the displayed tax and totals reproducible from the printed lines.

Final numbers use the issue date’s year. The counter is written before the finalized record, so a failure can consume a number instead of reusing it. Draft identifiers do not enter the final numbering sequence.

Setup and configuration

You can run the credit note MCP server locally by cloning the repository, installing dependencies, and building it:

git clone https://github.com/theluckystrike/mcp-credit-note.git
cd mcp-credit-note
npm install && npm run build

Configure an MCP client to launch node with the resulting dist/index.js file. The repository vendors its @theluckystrike/* dependencies, so the source build does not require an additional package setup. The package is not published on npm, so an npx -y @theluckystrike/mcp-credit-note installation currently fails.

A hosted streamable-HTTP option is available at https://mcp.zovo.one/mcp/credit-note. It requires a bearer token from the connect or token endpoint. Clients that cannot add headers can provide the token in the URL path instead. Claude Desktop also has a downloadable .mcpb option from the project’s latest release.

Tools and capabilities

The credit note MCP server exposes these operations:

• Create, update, finalize, list, retrieve, and delete credit notes.
• Render a note as Markdown or as a self-contained printable HTML page. Draft renders include a DRAFT banner.
• Filter listings by recipient, reason, status, and issue-date period.
• Summarize finalized credits by currency, reason, and month, optionally within an issue-date period.
• Check license status and activate a license key.

credit_note_get accepts either a final number or draft identifier and returns lines, tax lines, totals, reason, and notes. The free tier allows ten finalized notes over its lifetime; drafts, reads, listings, rendering, deletion, and summaries are otherwise unlimited. Pro removes the finalized-note limit and the rendering footer.

Limitations and notes

Finalized notes are intentionally permanent. There is no accounting-platform connection, outbound delivery, or document-file generation: rendered Markdown or HTML is returned as text for the client to use. The hosted endpoint needs a token, while the local server keeps its records on the machine. License verification is performed offline.