# 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:

```bash
export MCP_ENABLE_WRITES=1
```

---

## Quickstart

### Option A – Docker (recommended for a first try)

From the repository root:

```bash
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:

```text
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:

   ```bash
   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:

   ```bash
   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](docs/clients.md) for concrete examples.

---

## Where to go next

* [Concepts & storage model](docs/concepts.md)
* [Docker details](docs/getting-started-docker.md)
* [MCP client configuration](docs/clients.md)
* [Tools reference](docs/tools.md)
* [Advanced deployment (SSE, OpenWebUI, systemd, reverse proxy)](docs/advanced.md)

---

## 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](LICENSE) for licensing details.