invoice-mcp

A local MCP server that turns invoice details into a formatted Excel workbook. Connect it to Claude or another MCP client to calculate totals or create an .xlsx invoice from a conversation.

• Two tools: calculate_invoice and create_invoice.

• JPY, USD, and EUR, with integer minor-unit calculations.

• Mixed tax rates, with tax rounded down once per rate.

• Excel formulas, cached totals, and an A4 portrait print layout.

• Local files only. The server makes no network requests and needs no API key.

Built with TypeScript, the official @modelcontextprotocol/sdk, ExcelJS, and Zod. Tests use Vitest.

Quick start

Install Node.js 20 or later, then run these commands from the repository root:

npm install && npm run build

Generate the included sample invoice without an AI client:

INVOICE_MCP_OUTPUT_DIR="$PWD/output" npm run sample

On PowerShell:

$env:INVOICE_MCP_OUTPUT_DIR = "$PWD/output"
npm run sample

This creates output/sample-invoice.xlsx and prints its absolute path, currency, and total: JPY 172,078. Repeating the command creates sample-invoice-1.xlsx, then sample-invoice-2.xlsx. The sample runner reads examples/sample-invoice.json; edit that file to try your own data. All sample parties and addresses are fictional, and the registration number is a format example.

Related MCP server: JP Invoice & Tax MCP

Connect to Claude

Claude Code

Use an absolute path to the built server:

claude mcp add invoice-mcp -- node /path/to/invoice-mcp/dist/index.js

To choose an output directory during registration:

claude mcp add --env INVOICE_MCP_OUTPUT_DIR=/absolute/path/to/invoices invoice-mcp -- node /path/to/invoice-mcp/dist/index.js

These follow the Claude Code MCP configuration. If Node.js is unavailable in the client's environment, replace node with the absolute path to the Node.js executable.

Claude Desktop

Add this entry to the mcpServers object in claude_desktop_config.json, then restart Claude Desktop. Use absolute paths; environment values in this JSON do not expand ~ or $HOME.

{
  "mcpServers": {
    "invoice-mcp": {
      "command": "node",
      "args": ["/path/to/invoice-mcp/dist/index.js"],
      "env": {
        "INVOICE_MCP_OUTPUT_DIR": "/absolute/path/to/invoices"
      }
    }
  }
}

On Windows, use JSON-escaped paths such as C:\\projects\\invoice-mcp\\dist\\index.js. The server uses stdio: standard output is reserved for MCP messages; errors go to standard error.

Try asking:

Create invoice INV-2026-002 from Example Studio, 1 Sample Lane, billing@example.com, to Sample Workshop, 2 Demo Street, accounts@example.org. Issue it on October 1, 2026, due October 31. Charge USD 80.00 per hour for 12.5 hours of design, with 10% tax. Save it as design-invoice.xlsx.

Tool input

Both tools accept the same object. unitPrice is expressed in major currency units, and taxRate is a percentage: 8 means 8%, not 0.08%.

{
  "issuer": {
    "name": "Example Studio",
    "address": "1 Sample Lane",
    "email": "billing@example.com",
    "registrationNumber": "T1234567890123"
  },
  "customer": {
    "name": "Sample Workshop",
    "address": "2 Demo Street",
    "email": "accounts@example.org"
  },
  "invoiceNumber": "INV-2026-002",
  "issueDate": "2026-10-01",
  "dueDate": "2026-10-31",
  "currency": "USD",
  "items": [
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unitPrice": "80.00",
      "taxRate": 10
    }
  ],
  "notes": "Please include the invoice number with your payment.",
  "outputFilename": "design-invoice.xlsx"
}

Names are limited to 100 characters, addresses to 300, and emails to 254. Numeric strings use a decimal point, without grouping separators or exponent notation. Negative prices and credit notes are not supported. Each price, line amount, subtotal, and total must fit within 9,999,999,999 minor units so the generated Excel formulas retain integer precision.

calculate_invoice

Returns JSON as MCP text content. It does not create files or directories. For the USD example above:

{
  "currency": "USD",
  "minorUnitDigits": 2,
  "lines": [
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unitPriceMinor": 8000,
      "taxRate": "10",
      "amountMinor": 100000
    }
  ],
  "subtotalMinor": 100000,
  "taxes": [
    { "rate": "10", "taxableMinor": 100000, "taxMinor": 10000 }
  ],
  "taxMinor": 10000,
  "totalMinor": 110000,
  "total": "1100.00"
}

Fields ending in Minor are integers in yen or cents. total is a decimal string in major currency units. Tax groups are sorted by rate, including a zero-rate group when present.

create_invoice

Uses the same calculation and returns JSON as MCP text content:

{
  "path": "/absolute/path/to/invoices/design-invoice.xlsx",
  "currency": "USD",
  "totalMinor": 110000,
  "total": "1100.00"
}

Invalid inputs and filesystem failures produce an MCP tool error (isError: true) with a descriptive message.

Calculation rules

1. Parse decimal input directly into scaled integers with BigInt. Money is never calculated using floating-point arithmetic in the server.

2. Convert unit prices to the currency's smallest unit: whole yen for JPY, cents for USD/EUR.

3. Multiply each price by its quantity using integer arithmetic. If a fractional quantity creates a fraction of a yen or cent, round the line amount down to the nearest minor unit.

4. Sum line amounts by tax rate, then round each group's tax down once. Sum those taxes and add them to the subtotal.

For example, two JPY 19 lines at 8% have a taxable amount of JPY 38 and tax of JPY 3. Rounding each line's tax separately would produce JPY 2; this server groups the lines first. Tax rates are provided by the caller; the server does not select a rate or verify a registration number against a registry.

Editing and printing the workbook

The workbook contains issuer and customer details, dates, an item table, taxable amounts and tax for each rate, total due, and optional notes. Monetary cells use currency codes and thousands separators. The print area is set to A4 portrait, one page wide, with additional pages for longer invoices.

Line amounts, subtotal, tax breakdown, tax total, and total due are Excel formulas. A hidden column holds integer minor-unit calculations. Cached results are included because ExcelJS writes formulas but does not evaluate them; the workbook requests recalculation when opened in Excel or another compatible spreadsheet app. The ExcelJS documentation describes this formula/result model.

You can edit descriptions, quantities, and prices in existing item rows. Tax-rate dropdowns include the rates in the generated invoice, so lines can move between those groups. Keep the input precision and amount limits above when editing. To add lines or introduce a new tax rate, generate a new invoice. JSON tool results describe the original calculation and do not track later workbook edits.

Output directory and filenames

INVOICE_MCP_OUTPUT_DIR selects the only output directory. If unset, it defaults to ~/Documents/invoices using the current user's home directory. The directory is created when needed. Absolute paths are recommended; relative environment values resolve against the server's working directory.

Tool input cannot override the directory. Filenames containing /, \, or .. are rejected, as are control characters and reserved filename characters. The server resolves the configured directory and creates each file exclusively, adding -1, -2, and so on for collisions. This also prevents overwriting through an existing filename symlink and handles concurrent creates.

The output directory is trusted local configuration. Keep it under your control. No invoice data is uploaded by this server; your AI client's own handling of conversation data is separate.

Development and verification

npm run build && npm test && npm run lint && npx tsc --noEmit

npm test builds the server and runs tests for:

• Mixed tax rates, grouped rounding, fractional quantities, JPY units, and USD/EUR cents.

• Registration numbers, dates, numeric precision, and invalid input.

• Path traversal rejection, filename separators, symlinks, and concurrent collision handling.

• Reading generated workbooks back with ExcelJS to verify formulas, cached totals, and print settings.

• Launching the compiled stdio server with the official MCP client, calling tools/list to verify exactly two tools, and exercising both tools.

• Generating examples/sample-invoice.json and checking its expected total.

Test files and temporary outputs stay inside the repository. Tests remove their own output directories. Generated workbooks, build output, and local npm cache are ignored by Git. Runtime code is in src/; tests are in src/__tests__/.

License

MIT, copyright Sho Kuroda.