MAD invoiceMCP Server

MAD invoiceMCP provides a local, single‑company invoicing MCP server that ingests JSON data, renders invoices with LaTeX, and outputs PDFs. It is designed for straightforward, offline workflows on a single machine with a simple storage directory.

How to use

You interact with MAD invoiceMCP through an MCP client. You can create invoices from JSON data, render them into final PDFs, and manage their status from draft to final. Use the client to list invoices, read individual invoices, update their data, and trigger rendering to PDF. The server stores all invoices locally and exposes a lightweight web interface for overview and detail pages.

To run locally, choose either Docker for a quick start or a native Python STDIO setup. In both cases you will enable write access so you can create and modify invoices during your session.

How to install

Prerequisites you need before starting:

Python 3.10 or newer (tested with Python 3.11) and LaTeX (recent TeX Live release, 2024 or newer recommended). If you prefer not to install LaTeX locally, you can use the provided Docker image that already includes TeX Live.

Installable environments and initial setup steps depend on whether you choose Docker or a local STDIO setup.

Option A – Docker (recommended for a first try)

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

Option B – Local MCP server (stdio)

If you already have a compatible TeX Live installation and prefer running locally, follow these steps to start the MCP server over stdio.

Create a Python virtual environment, activate it, and install dependencies from the requirements file.

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

Option B – Local MCP server (stdio) continued

Start the MCP server over stdio with write access enabled.

MCP_ENABLE_WRITES=1 python -m bridge --transport stdio

Security and configuration notes

Writes are disabled by default to prevent unintended modifications. Enable writes only when you are actively creating or updating invoices by setting MCP_ENABLE_WRITES=1 in your environment. The server stores all data locally under the .mad_invoice directory when using Docker or your project workspace in the local setup.

What to expect next

You will gain access to a simple web overview and detail pages for existing invoices, along with MCP tools that let you list, read, update, and render invoices. If you need to render invoices, LaTeX templates and a PDF output are produced locally.

Available tools

list_invoices

List all invoices stored locally with their basic metadata.

read_invoice

Read a single invoice by its identifier to view details.

update_invoice

Update data for an existing invoice in the local store.

render_invoice

Render an invoice from JSON data into a LaTeX source and finalize it as a PDF.