MCP Invoice Maker

A local-first MCP project for creating PDF invoices from SQLite data.

Current Step: Database

Initialize the local SQLite database:

npm run db:init

Add sample data:

npm run db:seed

Inspect available tables:

npm run db:inspect

The database is created at data/invoices.sqlite and is ignored by git.

Planned Build Order

1. SQLite database for invoice data
2. HTML invoice page/template
3. MCP JSON tools for creating, rendering, and fetching invoices
4. Puppeteer PDF rendering

HTML Invoice Template

The invoice template lives at templates/invoice.html with styles in templates/invoice.css.

It is based on the Beam Beam Digital PDF invoice design and uses:

• Montserrat for general invoice text and BEAM BEAM
• Bodoni Moda for Digital and With thanks

Invoice Input Schema

The create-invoice JSON input schema lives at src/schemas/create-invoice.schema.json.

An example payload lives at examples/create-invoice.json.

The required invoice input is intentionally minimal:

• client_name
• work_carried_out
• hours

The optional issue_date can override the current local date.

MCP Server

Run the local MCP server over stdio:

npm start

Codex project-local MCP config lives at .codex/config.toml and registers this server as:

invoice_maker

After adding or changing MCP config, restart Codex or open a new Codex thread so the tools are loaded.

Current tools:

• add_client
• update_client
• list_clients
• create_invoice
• get_invoice
• list_client_invoices

The create_invoice tool treats an invoice request as a PDF request: it writes the invoice data to SQLite, renders the invoice PDF, and returns the invoice data with a pdf.path and pdf.url.

Render HTML

Render an existing invoice to a local HTML file:

npm run render:html -- 001

This writes to output/invoice-001.html.

Render PDF

Render an existing invoice to a local PDF file:

npm run render:pdf -- 001

This writes:

• output/invoice-001.html
• output/invoice-001.pdf

PDF rendering uses puppeteer-core and the Chrome installed at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome. You can override the browser path with PUPPETEER_EXECUTABLE_PATH.