🧾 MCP Invoice Generator

Generate PDF invoices via a Model Context Protocol (MCP) server.

This server is primarily designed for local use via stdio. It generates PDF invoices directly on your machine using Typst — a modern, fast typesetting system that replaces traditional HTML/CSS-to-PDF pipelines. Templates are clean, readable .typ files compiled to pixel-perfect PDFs in milliseconds. Billing data (issuers, clients, services) is loaded from a local TOML file, making it easy to manage without any external service or database.

Features

• PDF invoice generation — Typst template compiled to PDF

• MCP server — generate_invoice and get_default_values tools accessible by an LLM

• TOML configuration — issuers, clients and services defined in data/billing.toml

• FastMCP — modern MCP server framework

• Typst — typesetting system for PDF rendering

• pydantic-settings — application settings management

• dynaconf — TOML billing data loading

• uv — dependency management

• ruff — linter & formatter

• Dockerfile — multi-stage build ready for production

Requirements

• uv

• Docker / Podman (only required to build and run the container image)

Getting Started

1. Clone the repository

git clone https://github.com/pirocheto/mcp-invoice-generator
cd mcp-invoice-generator

2. Billing data

Copy and fill in the data file:

cp data/billing.toml.example data/billing.toml

This file is the core data source for invoice generation. It defines the people, companies, and services that can appear on your invoices. The get_default_values tool reads directly from this file, and generate_invoice uses the provided data to populate the PDF.

You can define multiple entries in each section — simply repeat the [[issuers]], [[services]], or [[clients]] block.

[[issuers]]
name = "Jane Doe"
address = "12 rue de la Paix"
city = "Lyon"
postal = "69001"
email = "jane.doe@example.com"
siren = "123 456 789"
siret = "123 456 789 00012"
vat_number = "FR 12 123 456 789"
iban = "FR76 ..."
bic = "BNPAFRPPXXX"
tax_rate = 0.2

[[services]]
name = "consulting"
daily_rate = 600
description = "Professional services — consulting"

[[clients]]
name = "Acme Corp"
address = "42 avenue des Champs-Élysées"
city = "Paris"
postal = "75008"
siren = "987 654 321"
vat_number = "FR 98 987 654 321"

3. Environment variables

The application is configured via environment variables (prefixed with APP_) or a .env file at the project root.

Relative paths are resolved from the project root. Absolute paths are used as-is.

Installation

Local (stdio)

Clone the repository and point your MCP client (e.g. Claude Desktop, Github Copilot, OpenCode, etc) to it:

{
  "mcpServers": {
    "invoice-generator": {
      "type": "stdio",
      "env": {
        "APP_DATA_FILE": "./data/billing.toml",
        "APP_OUTPUT_DIR": "./outputs",
        "APP_TEMPLATE_DIR": "./templates"
      },
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-invoice-generator",
        "--",
        "fastmcp",
        "run"
      ]
    }
  }
}

Replace /path/to/mcp-invoice-generator with the absolute path where you cloned the repository.

Docker

The project includes a multi-stage Dockerfile optimised for production:

• Builder stage — installs dependencies with uv using layer caching

• Runtime stage — minimal python:3.13-slim image with only the virtual environment copied over

• Typst binary copied from the official ghcr.io/typst/typst image

• Runs as a non-root user (nonroot, uid 999)

• Exposes the MCP server via uvicorn on port 8000

# Build the image
make build

# Run the container (mounts data/, outputs/ and templates/, exposes port 8000)
make start

data/billing.toml must exist before running the container — it is mounted at runtime and is never baked into the image.

MCP Tools

get_default_values — Returns all default billing data from billing.toml, including available issuers, services, and clients.

generate_invoice — Generates a PDF invoice from flat input fields.

Returns the path to the generated PDF file.

Template

The invoice template is located in templates/invoice.typ and is written in Typst, a modern typesetting language. It receives all invoice fields as named parameters and is compiled to PDF by the typst Python package.

The included template is designed for French freelancers: it is based on a daily rate (TJM), computes subtotal, VAT, and total, and formats all monetary values using French conventions (e.g. 3 000,00 €).

To customise the invoice layout, edit templates/invoice.typ directly.

→ View example invoice

Template parameters

All parameters are passed as flat named arguments to the Typst template function.

Issuer

Client

Service

Invoice

Development

make dev

Starts the server with --reload via dev.fastmcp.json.

Make Commands

License

MIT — see LICENSE.