Skip to main content
Glama
create-beautiful-invoices-mcp

create-beautiful-invoices-mcp

by Danilqa
README.md
# create-beautiful-invoices-mcp

> ๐Ÿงพ An MCP server that creates beautiful, real PDF invoices. Ask your AI assistant for an invoice and get a PDF on disk.

The invoices use the design of [sample-invoice-generator](https://github.com/Danilqa/sample-invoice-generator): a large amount due, the parties and dates, line items, totals with VAT and bank transfer details, set in Inter on A4.

## โšก Quickstart

You need Node 24.

Claude Code:

```bash
claude mcp add invoices -- npx -y create-beautiful-invoices-mcp
```

Claude Desktop, Cursor and other clients take the same command in their MCP config:

```json
{
  "mcpServers": {
    "invoices": {
      "command": "npx",
      "args": ["-y", "create-beautiful-invoices-mcp"],
      "env": { "INVOICES_DIR": "/Users/you/Invoices" }
    }
  }
}
```

Then ask: _"Invoice Fabrikam for 7.5 hours of design review at ยฃ95.50 an hour, with 20% VAT, due in 30 days."_

## ๐Ÿ› ๏ธ Tools

### `create_invoice`

Renders the invoice to a PDF, saves it to the invoices folder and returns its path with a link to the file. An invoice number that already has a PDF gets a numbered copy, such as `invoice-INV-001 (2).pdf`, so no invoice is ever replaced.

| Field                  | Description                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `invoiceNumber`        | Unique number, also the payment reference                                                                         |
| `issueDate`, `dueDate` | `YYYY-MM-DD`. Today and 30 days later by default. The due date can't be before the issue date                     |
| `currency`             | `GBP`, `EUR`, `USD`, `AUD`, `BRL`, `CAD`, `CHF`, `CNY`, `INR`, `JPY`, `KRW`, `NZD`, `RUB`, `SGD` or `ZAR`         |
| `seller`               | `name`, and optionally `address`, `email`, `phone`, `taxNumber` and `logo`, an absolute path to a PNG or JPEG     |
| `client`               | `name`, and optionally `address` and `email`                                                                      |
| `items`                | At least one `{ description, quantity, unitPrice }`. `quantity` defaults to 1                                     |
| `discountRate`         | Discount on the subtotal in percent, taken off before tax                                                         |
| `taxRate`, `taxLabel`  | Tax in percent and its name, `VAT` by default. Without a rate, the invoice has no tax                             |
| `notes`                | Text under the totals, such as a PO number or a thank-you                                                         |
| `payment`              | `uk-bank-transfer` with a sort code and account number, or `iban-transfer` with an IBAN and an optional SWIFT/BIC |

## โš™๏ธ Configuration

| Variable           | Default      | Description                                         |
| ------------------ | ------------ | --------------------------------------------------- |
| `INVOICES_DIR`     | `~/Invoices` | Folder the PDFs are saved to                        |
| `INVOICE_DEFAULTS` |              | JSON file with the fields every invoice starts from |

### Saved defaults

Save what repeats in a JSON file and point `INVOICE_DEFAULTS` at it. The tool then asks only for the rest, such as the client and the items:

```json
{
  "seller": {
    "name": "Northwind Studio Ltd",
    "address": "12 Hoxton Square\nLondon N1 6NU",
    "email": "billing@northwind.studio",
    "taxNumber": "GB123456789",
    "logo": "/Users/you/Invoices/logo.png"
  },
  "payment": {
    "method": "uk-bank-transfer",
    "accountName": "Northwind Studio Ltd",
    "sortCode": "20-00-00",
    "accountNumber": "55779911"
  },
  "currency": "GBP",
  "taxRate": 20,
  "dueInDays": 14
}
```

The file can set `seller`, `payment`, `currency`, `taxRate`, `taxLabel`, `notes` and `dueInDays`. A field given in a call replaces its default as a whole. The server doesn't start with a file it can't read, so a typo never turns into a wrong invoice.

## ๐Ÿง‘โ€๐Ÿ’ป Development

pnpm 12 and Node 24. See [AGENTS.md](AGENTS.md) for the layout and rules.

```bash
pnpm install
pnpm validate   # format check, lint, typecheck and tests
pnpm inspect    # the server from source in the MCP Inspector
pnpm build      # packages/mcp-server/dist/main.js
```

## ๐Ÿ“„ License

[MIT](LICENSE)