MAD invoiceMCP server

Mechatronics Advisory & Design (M.A.D. Solutions) – JSON → LaTeX → PDF invoicing server with local file storage.

<img width="2048" height="786" alt="logo" src="https://github.com/user-attachments/assets/203a5a7b-4802-4edc-8250-ddaf7143186c" />

What is this?

MAD invoiceMCP is a small Model Context Protocol (MCP) server that lets you create, store, and render invoices for a single company using JSON data and LaTeX templates.

It is designed for local, single‑user workflows:

• one repository and one .mad_invoice/ data directory
• no multi‑tenant or multi‑project switching
• no external database or cloud backend

Best fit: freelancers and small businesses who want to generate invoices on their own machine.

Not designed as:

• a multi‑tenant system for tax advisors or agencies with many clients
• a hosted SaaS product
• a full accounting or ERP system

---

Key features

• JSON → LaTeX → PDF invoice rendering pipeline
• draft → final lifecycle with immutable final invoices
• payment status tracking (open, paid, overdue, cancelled)
• optional VAT handling and German §19 UStG ("small business") mode
• language‑aware labels and dates (German / English)
• simple web overview and detail pages for existing invoices
• MCP tools for listing, reading, updating, and rendering invoices

---

Requirements

• Python: 3.10 or newer (tested with 3.11)

• LaTeX: a recent TeX Live release (2024 or newer recommended)

  • or use the Docker image, which already includes TeX Live

• Optional: Docker, if you prefer not to manage Python and LaTeX locally

Write‑capable tools are disabled by default. To allow creating or updating invoices, set:

export MCP_ENABLE_WRITES=1

---

Quickstart

Option A – Docker (recommended for a first try)

From the repository root:

docker build -t mad-invoice-mcp .
docker run --rm \
  -p 8000:8000 \
  -v $(pwd)/.mad_invoice:/app/.mad_invoice \
  -e MCP_ENABLE_WRITES=1 \
  mad-invoice-mcp

Then open the web UI in your browser:

http://localhost:8000/invoices

The container image already includes a recent TeX Live installation, so you do not need LaTeX on the host.

---

Option B – Local MCP server (stdio)

Use this path if you have a compatible TeX Live installation on your machine.

1. Create a virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate  # on Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

2. Start the MCP server over stdio:

   MCP_ENABLE_WRITES=1 python -m bridge --transport stdio
   

Most MCP‑capable clients (Claude Desktop, Cline, Continue, etc.) can then be pointed at this server using their standard command/args configuration. See MCP client configuration for concrete examples.

---

Where to go next

• Concepts & storage model
• Docker details
• MCP client configuration
• Tools reference
• Advanced deployment (SSE, OpenWebUI, systemd, reverse proxy)

---

Code generation notice

Most of this repository's code was originally produced with AI assistants. The project is maintained and reviewed by a human, but you should still treat it as experimental software and review it carefully before using it in production.

---

License

See LICENCE for licensing details.