mcp-server · invoicebox — Claude Code MCP server: invoices, shipments, refunds
An InvoiceBox MCP server that lets an assistant issue invoices, check payment, confirm shipments and refund money, with a human approving each write.
claude mcp add --env INVOICEBOX_API_TOKEN=<INVOICEBOX_API_TOKEN> --env INVOICEBOX_MERCHANT_ID=<INVOICEBOX_MERCHANT_ID> --env INVOICEBOX_ENV=<INVOICEBOX_ENV> --env INVOICEBOX_TOOLSETS=<INVOICEBOX_TOOLSETS> --env INVOICEBOX_STATE_DIR=<INVOICEBOX_STATE_DIR> --transport stdio invoicebox-mcp-server -- npx -y @invoicebox/mcp-serverWhat mcp-server does
This server exposes InvoiceBox as a toolset for your assistant. Looking up company details by tax ID, fetching an invoice by id or your own number, listing invoices and shipments — all of that runs without approval. Invoice creation, cancellation, shipment confirmation and refunds work in two steps: the first call hands back a summary plus a single-use token valid for 15 minutes, and a second call with that token carries the operation out. Nothing reaches the API until a person signs off.
Default permissions are read-only. Writes turn on explicitly: INVOICEBOX_TOOLSETS=write adds invoicing, cancellation and shipping, refund adds refunds. Amounts travel as integer kopecks in a string, so a float can't shave off a kopeck. Above INVOICEBOX_CONFIRM_THRESHOLD (100 000 ₽ by default) the server asks the human separately rather than trusting a number the model produced. Closing documents — the act, TORG-12, the invoice and UPD — come from create_shipment; no separate tool exists for them.
You need INVOICEBOX_API_TOKEN from your account and INVOICEBOX_ENV set to demo or production. Merchant operations also need INVOICEBOX_MERCHANT_ID; organization operations need INVOICEBOX_COUNTERPARTY_ID. Skip INVOICEBOX_STATE_DIR and duplicate protection survives only within a single run. The demo store is shared, so test invoices are visible to every reader — keep real company details out.
What it helps with
- issue an invoice to a company, sole trader or individual from a chat
- check whether an invoice was paid and what status it has
- confirm a shipment and get the closing documents for it
- look up counterparty details by tax ID
- refund a payment in full or per line item
Example prompts for the agent
- Find the company details for tax ID 7707083893
- Create an invoice for 12200 kopecks for a consultation, buyer is a legal entity
- Confirm shipment for order 1042 and list the documents it will generate
How to install mcp-server
Platform CLI
claude mcp add --env INVOICEBOX_API_TOKEN=<INVOICEBOX_API_TOKEN> --env INVOICEBOX_MERCHANT_ID=<INVOICEBOX_MERCHANT_ID> --env INVOICEBOX_ENV=<INVOICEBOX_ENV> --env INVOICEBOX_TOOLSETS=<INVOICEBOX_TOOLSETS> --env INVOICEBOX_STATE_DIR=<INVOICEBOX_STATE_DIR> --transport stdio invoicebox-mcp-server -- npx -y @invoicebox/mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add invoicebox-mcp-server --env INVOICEBOX_API_TOKEN=<INVOICEBOX_API_TOKEN> --env INVOICEBOX_MERCHANT_ID=<INVOICEBOX_MERCHANT_ID> --env INVOICEBOX_ENV=<INVOICEBOX_ENV> --env INVOICEBOX_TOOLSETS=<INVOICEBOX_TOOLSETS> --env INVOICEBOX_STATE_DIR=<INVOICEBOX_STATE_DIR> -- npx -y @invoicebox/mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"invoicebox-mcp-server": {
"command": "npx",
"args": [
"-y",
"@invoicebox/mcp-server"
],
"env": {
"INVOICEBOX_API_TOKEN": "<INVOICEBOX_API_TOKEN>",
"INVOICEBOX_MERCHANT_ID": "<INVOICEBOX_MERCHANT_ID>",
"INVOICEBOX_ENV": "<INVOICEBOX_ENV>",
"INVOICEBOX_TOOLSETS": "<INVOICEBOX_TOOLSETS>",
"INVOICEBOX_STATE_DIR": "<INVOICEBOX_STATE_DIR>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"invoicebox-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@invoicebox/mcp-server"
],
"env": {
"INVOICEBOX_API_TOKEN": "<INVOICEBOX_API_TOKEN>",
"INVOICEBOX_MERCHANT_ID": "<INVOICEBOX_MERCHANT_ID>",
"INVOICEBOX_ENV": "<INVOICEBOX_ENV>",
"INVOICEBOX_TOOLSETS": "<INVOICEBOX_TOOLSETS>",
"INVOICEBOX_STATE_DIR": "<INVOICEBOX_STATE_DIR>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e INVOICEBOX_API_TOKEN=<INVOICEBOX_API_TOKEN> -e INVOICEBOX_MERCHANT_ID=<INVOICEBOX_MERCHANT_ID> -e INVOICEBOX_ENV=<INVOICEBOX_ENV> -e INVOICEBOX_TOOLSETS=<INVOICEBOX_TOOLSETS> -e INVOICEBOX_STATE_DIR=<INVOICEBOX_STATE_DIR> invoicebox-mcp-server npx -y @invoicebox/mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-server
How do I install mcp-server in Claude Code?
Run `claude mcp add mcp-server -e INVOICEBOX_API_TOKEN=<INVOICEBOX_API_TOKEN> -e INVOICEBOX_MERCHANT_ID=<INVOICEBOX_MERCHANT_ID> -- npx -y @invoicebox/mcp-server`. Then check that the server answers a tool-list request.
What does mcp-server do?
It gives an assistant InvoiceBox tools: tax ID lookups, invoice and shipment reads, plus invoice creation, cancellation, shipping and refunds once the write and refund toolsets are switched on.
What stops an accidental payment operation?
Read-only is the default, so writes require INVOICEBOX_TOOLSETS. Money operations also need the two-phase token, and amounts over the confirmation threshold get a separate human check.
Similar MCP servers
All MCP servers for Finance and business →mcp-server by other authors comes first.
