Which integrations are available for this server?

Generates PDF invoices using Typst templates, enabling customizable invoice layouts with automatic VAT calculation and French formatting.

How do I use MCP Invoice Generator?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Invoice Generator Create an invoice for client Acme Corp for 5 days of consulting" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Invoice Generator

by pirocheto

Overview Schema Source Related Servers Discussions Admin

Local

🧾 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

Related MCP server: DocFiller

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.

Variable	Default	Description
`APP_SERVICE_NAME`	`Invoice Generator Service`	Name of the MCP server
`APP_ENV`	`development`	Environment (`development` or `production`)
`APP_OUTPUT_DIR`	`outputs`	Directory where generated PDFs are saved
`APP_TEMPLATE_DIR`	`templates`	Directory containing Typst invoice templates
`APP_DATA_FILE`	`data/billing.toml`	Path to the billing data TOML file

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.

Parameter	Type	Default	Description
`invoice_number`	`str`	—	Invoice number
`invoice_date`	`date`	today	Invoice date (ISO 8601)
`issuer_name`	`str`	—	Issuer full name
`issuer_address`	`str`	—	Issuer street address
`issuer_city`	`str`	—	Issuer city
`issuer_postal`	`str`	—	Issuer postal code
`issuer_email`	`str`	—	Issuer email address
`issuer_siren`	`str`	—	Issuer SIREN number
`issuer_siret`	`str`	—	Issuer SIRET number
`issuer_vat_number`	`str`	—	Issuer VAT number
`issuer_iban`	`str`	—	Issuer IBAN
`issuer_bic`	`str`	—	Issuer BIC / SWIFT code
`issuer_tax_rate`	`float`	—	VAT rate (e.g. `0.2` for 20%)
`service_daily_rate`	`int`	—	Daily rate in euros (TJM)
`service_description`	`str`	—	Service description line on invoice
`service_days`	`int`	—	Number of days worked
`client_name`	`str`	—	Client company name
`client_address`	`str`	—	Client street address
`client_city`	`str`	—	Client city
`client_postal`	`str`	—	Client postal code
`client_siren`	`str`	—	Client SIREN number
`client_vat_number`	`str`	—	Client VAT number

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

Parameter	Type	Description
`issuer_name`	`str`	Full name
`issuer_address`	`str`	Street address
`issuer_city`	`str`	City
`issuer_postal`	`str`	Postal code
`issuer_email`	`str`	Email address
`issuer_siren`	`str`	SIREN number
`issuer_siret`	`str`	SIRET number
`issuer_vat_number`	`str`	VAT number
`issuer_iban`	`str`	IBAN
`issuer_bic`	`str`	BIC / SWIFT code
`issuer_tax_rate`	`float`	VAT rate (e.g. `0.2` for 20%)

Client

Parameter	Type	Description
`client_name`	`str`	Company name
`client_address`	`str`	Street address
`client_city`	`str`	City
`client_postal`	`str`	Postal code
`client_siren`	`str`	SIREN number
`client_vat_number`	`str`	VAT number

Service

Parameter	Type	Description
`service_daily_rate`	`int`	Daily rate in euros (TJM)
`service_description`	`str`	Description line on invoice
`service_days`	`int`	Number of days worked

Invoice

Parameter	Type	Description
`invoice_number`	`str`	Invoice number
`invoice_date`	`str`	Invoice date (DD/MM/YYYY)

Development

make dev

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

Make Commands

Command	Description
`make dev`	Start server in development mode with auto-reload
`make test`	Run tests with coverage report
`make build`	Build the Docker image
`make start`	Run the container in production
`make run-inspector`	Launch the MCP inspector

License

MIT — see LICENSE.

Available Tools

2 tools

generate_invoiceB

Generate an invoice for a client in PDF format. The invoice is saved to the outputs directory and the path is returned.

ParametersJSON Schema

Name	Required	Description	Default
`data`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses a key side effect (saving the invoice to the outputs directory) and the return value (the path). However, it does not mention potential errors, overwriting behavior, permissions, or the fact that the operation creates a file, which is only implied. It provides basic transparency but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main action, and every word earns its place. It is succinct, clear, and free of unnecessary detail, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description is inadequate for the complexity of the input. It does not explain the structure or purpose of the 'data' parameter, nor does it mention that the data must include issuer, client, and service details. The sole focus on output leaves a significant gap in understanding how to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain what data should contain or provide any context for the numerous required fields. The schema's field names are self-explanatory to some degree, but the description adds no value beyond the schema, leaving the agent to guess at the meaning and format of the nested data object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates an invoice for a client in PDF format, and it distinguishes itself from the sibling tool get_default_values by indicating its unique output (PDF saved to outputs directory). It uses a specific verb and resource, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as get_default_values. It does not mention any prerequisites, exclusions, or scenarios where a different tool would be more appropriate. Users are left to infer usage from the description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_default_valuesA

Get the default values for invoices, including available issuers, services, and clients.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry the full burden of behavioral disclosure. The verb 'Get' implies a read-only operation, but the description does not explicitly state the absence of side effects, permissions required, or other behavioral traits. It is adequate but could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, substantive sentence that front-loads the action and resource. Every word earns its place, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter tool with a simple retrieval function, the description is complete. It lists the key components of the response, and the presence of an output schema covers return value details. No additional context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds value by detailing what the default values include (issuers, services, clients), which is helpful context even though there are no input parameters to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('default values for invoices'), and it enumerates the contents (issuers, services, clients). This distinguishes it from the sibling 'generate_invoice' tool, which focuses on creation rather than retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as a preparatory step for generating invoices, but it does not explicitly state when to use this tool over generate_invoice or provide alternative scenarios. The context is clear but lacks explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.1.0Aug 6, 2026
- First observedgenerate_invoice
- First observedget_default_values

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-08-06 04:10 across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one retrieves configuration defaults, the other generates the invoice. There is no overlap or confusion between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with lowercase and underscores ('get_default_values', 'generate_invoice'). The style is uniform across the set.

Tool Count3/5

With only two tools, the server feels thin for an invoice generator, though the core functionality (fetching defaults and generating) is present. It falls at the lower end of acceptable tool counts.

Completeness4/5

The set covers the essential flow of retrieving defaults and generating an invoice, but lacks auxiliary operations such as listing previously generated invoices or managing invoice data. These are minor gaps that agents can work around.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

invoice-pdf-billing-generator A
io.github.theluckystrike
Create PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
Payments & Billing Finance
131
DocuQueue MCP B
io.github.dvcoolarun
Generate PDFs from templates via AI chat. Works with Claude, ChatGPT, Cursor, and any MCP client.
Workplace & Productivity Content Management Systems
1111
mcp-serverOAuth
com.pdfgate
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Documentation Access File Systems
1
Jupiter Invoice
com.jupiterinvoice
Create and manage invoices and customers on Jupiter Invoice (MCP, API-key auth).
Payments & Billing Finance
2

Related MCP Servers

beautiful-pdf-mcp
Design Tools Workplace & Productivity Developer Tools
Kreminskaya
A
license
Not graded
quality
D
maintenance
MCP server that lets AI agents produce print-ready, typographically correct PDFs using Typst, with a page-as-canvas engine, multiple templates, and per-page layout quality control.
Updated 3 months ago (2026-06-12 11:29 UTC)
MIT
DocFiller
Content Management Systems AI & Machine Learning
adriangonzalezIABD
F
license
Not graded
quality
D
maintenance
Enables generating PDFs from DOCX/ODT templates using MCP with support for OpenAI or local Ollama models.
Updated 3 months ago (2026-06-17 10:59 UTC)
-
Invoice MCP Server
Payments & Billing Finance
morenoraf
A
license
Not graded
quality
D
maintenance
Enables invoice management through MCP, including customer, invoice, and report operations with CLI and web interfaces.
Updated 8 months ago (2026-01-09 11:41 UTC)
MIT
MCP Invoice Maker
Databases File Systems
amyvarga
F
license
Not graded
quality
C
maintenance
A local-first MCP server for creating PDF invoices from SQLite data, supporting client management and invoice generation.
Updated 3 months ago (2026-06-24 12:33 UTC)
-

🧾 MCP Invoice Generator

Features

Requirements

Getting Started

1. Clone the repository

2. Billing data

3. Environment variables

Installation

Local (stdio)

Docker

MCP Tools

Template

Template parameters

Development

Make Commands

License

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

beautiful-pdf-mcp

DocFiller

Invoice MCP Server

MCP Invoice Maker