MAD invoiceMCP server

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

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

Related MCP server: Invompt MCP

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.