billingengine-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timo Kleemann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# BillingEngine MCP server
+
+Create customers and invoices, look up open invoices and record payments in
+[BillingEngine](https://www.billingengine.com) by talking to Claude, Cursor or any other
+[MCP](https://modelcontextprotocol.io) client:
+
+> "Create an invoice for Malermeister Müller over 100 euros."
+>
+> "Which invoices are overdue?"
+>
+> "Müller paid invoice 2610030028, record the payment."
+
+BillingEngine is invoicing software for freelancers and small businesses with
+[e-invoicing](https://www.billingengine.com/en/features) (XRechnung and ZUGFeRD / Factur-X),
+DATEV export and a German and English interface. The server is a thin layer over the
+[BillingEngine API](https://www.billingengine.com/en/api) and runs on your computer.
+
+## Requirements
+
+- Node.js 20 or newer
+- A BillingEngine account on a paid plan. The API is not available in the Free plan.
+- Your API key from **Settings > API** in BillingEngine
+
+## Setup
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "billingengine": {
+      "command": "npx",
+      "args": ["-y", "billingengine-mcp"],
+      "env": { "BILLINGENGINE_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```sh
+claude mcp add billingengine --env BILLINGENGINE_API_KEY=your-api-key -- npx -y billingengine-mcp
+```
+
+### Cursor and other clients
+
+Use the same `command`, `args` and `env` as above in the MCP settings of your client.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `find_customers` | Searches customers by company, name or email |
+| `create_customer` | Creates a customer |
+| `update_customer` | Changes a customer |
+| `create_invoice` | Creates a **draft** invoice for a customer |
+| `update_invoice` | Changes a draft invoice |
+| `list_invoices` | Lists invoices, filtered by status, customer, number or date |
+| `get_invoice` | Returns one invoice with items and payment status |
+| `download_invoice` | Saves the PDF or the XML e-invoice to your Downloads folder |
+| `record_payment` | Records a payment for sent invoices |
+| `list_payments` | Lists payments, optionally for one invoice |
+
+## What it does and does not do
+
+- Invoices are created as **drafts**. Nothing is sent to your customers; you review and send
+  the invoice in BillingEngine. Every result contains a link to open the draft.
+- Prices are net. Number, language, texts, VAT treatment and payment terms come from your
+  account settings, exactly as in the invoice form.
+- **Nothing can be deleted** through this server.
+- New invoices count towards the monthly invoice maximum of your plan.
+- The API allows 60 requests per minute per key.
+- Your key stays on your computer and is only sent to BillingEngine.
+
+If a key is ever exposed, generate a new one under **Settings > API**. The old key stops working
+immediately. The settings also show when the key was last used.
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `BILLINGENGINE_API_KEY` | Your API key (required) |
+| `BILLINGENGINE_URL` | Base URL, defaults to `https://www.billingengine.com` |
+
+## Development
+
+```sh
+npm install
+npm run build
+BILLINGENGINE_API_KEY=... node dist/index.js
+```
+
+## License
+
+MIT. BillingEngine itself is a commercial service; see [billingengine.com](https://www.billingengine.com).

package/dist/client.js

@@ -0,0 +1,78 @@
+export class BillingEngineError extends Error {
+}
+export class BillingEngineClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async get(path, query = {}) {
+        const response = await this.fetch("GET", path, query);
+        return response.json();
+    }
+    async getFile(path) {
+        const response = await this.fetch("GET", path);
+        const disposition = response.headers.get("content-disposition") ?? "";
+        const match = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition);
+        return {
+            data: Buffer.from(await response.arrayBuffer()),
+            filename: match ? decodeURIComponent(match[1]) : path.split("/").pop(),
+        };
+    }
+    async post(path, body) {
+        const response = await this.fetch("POST", path, {}, body);
+        return response.json();
+    }
+    async patch(path, body) {
+        const response = await this.fetch("PATCH", path, {}, body);
+        return response.json();
+    }
+    async fetch(method, path, query = {}, body) {
+        const url = new URL(`/api/v1${path}`, this.baseUrl);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "User-Agent": "billingengine-mcp",
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            throw new BillingEngineError(`BillingEngine could not be reached at ${this.baseUrl}: ${error.message}`);
+        }
+        if (!response.ok)
+            throw new BillingEngineError(await describeFailure(response));
+        return response;
+    }
+}
+async function describeFailure(response) {
+    const text = await response.text();
+    let messages = [];
+    try {
+        const parsed = JSON.parse(text);
+        messages = parsed.errors ?? (parsed.error ? [parsed.error] : []);
+    }
+    catch {
+        // Not JSON, e.g. a proxy error page.
+    }
+    switch (response.status) {
+        case 401:
+            return "The API key was rejected. Check BILLINGENGINE_API_KEY (Settings > API in BillingEngine).";
+        case 403:
+            return messages.join("; ") || "This API key is not allowed to do that. The API needs a paid plan.";
+        case 429:
+            return "Too many requests: the limit is 60 per minute. Wait a moment and try again.";
+        default:
+            return `BillingEngine answered ${response.status}: ${messages.join("; ") || text.slice(0, 200)}`;
+    }
+}

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { BillingEngineClient, BillingEngineError } from "./client.js";
+const apiKey = process.env.BILLINGENGINE_API_KEY;
+if (!apiKey) {
+    console.error("BILLINGENGINE_API_KEY is not set. You find your key in BillingEngine under Settings > API.");
+    process.exit(1);
+}
+const baseUrl = process.env.BILLINGENGINE_URL ?? "https://www.billingengine.com";
+const client = new BillingEngineClient(baseUrl, apiKey);
+const INSTRUCTIONS = [
+    "BillingEngine is an invoicing application for freelancers and small businesses.",
+    "Look a customer up with find_customers before creating an invoice and never guess a customer id; ask which one is meant when several match.",
+    "Prices are net amounts, the tax rate and everything else not given come from the account's settings.",
+    "Invoices are created as drafts and are not sent: tell the user to review and send them in BillingEngine, using the app_url in the result.",
+    "Nothing can be deleted through this server.",
+].join(" ");
+const server = new McpServer({ name: "billingengine", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use YYYY-MM-DD");
+const page = z.number().int().min(1).optional().describe("Page of the list, starting at 1");
+const address = z.object({
+    line_1: z.string().describe("Street and number"),
+    line_2: z.string().optional(),
+    postal_code: z.string(),
+    city: z.string(),
+    region: z.string().optional(),
+    country: z.string().length(2).describe("ISO country code such as DE, AT or CH"),
+});
+const customerFields = {
+    company: z.string().optional(),
+    first_name: z.string().optional(),
+    last_name: z.string().optional(),
+    email: z.string().optional(),
+    phone: z.string().optional(),
+    vat_number: z.string().optional(),
+    buyer_reference: z.string().optional().describe("Leitweg-ID or buyer reference for e-invoices"),
+};
+const item = z.object({
+    title: z.string(),
+    price: z.number().describe("Net price per unit"),
+    description: z.string().optional(),
+    quantity: z.number().optional().describe("Defaults to 1"),
+    unit_code: z.string().optional().describe("UN/ECE unit code such as C62 (piece) or HUR (hour)"),
+    tax_rate: z.number().optional().describe("VAT rate in percent; defaults to the account's default tax"),
+});
+const invoiceFields = {
+    date: date.optional().describe("Invoice date, defaults to today"),
+    due_days: z.number().int().min(0).optional().describe("Days until payment is due"),
+    introduction: z.string().optional(),
+    signature: z.string().optional(),
+    service_period_start_date: date.optional(),
+    service_period_end_date: date.optional(),
+};
+const READ = { readOnlyHint: true, openWorldHint: false };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+async function respond(action) {
+    try {
+        const value = await action();
+        return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
+    }
+    catch (error) {
+        const message = error instanceof BillingEngineError ? error.message : `Unexpected error: ${error.message}`;
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+}
+function withAppUrl(invoice) {
+    return { ...invoice, app_url: `${baseUrl}/invoices/${invoice.id}/edit` };
+}
+function withInvoiceLinks(result) {
+    const body = result;
+    if (body.data)
+        return { ...body, data: body.data.map(withAppUrl) };
+    return body.id === undefined ? body : withAppUrl(body);
+}
+server.registerTool("find_customers", {
+    title: "Find customers",
+    description: "Lists customers, optionally filtered by a search text that matches company, names and email.",
+    inputSchema: { query: z.string().optional(), page },
+    annotations: READ,
+}, ({ query, page }) => respond(() => client.get("/customers", { query, page })));
+server.registerTool("create_customer", {
+    title: "Create a customer",
+    description: "Creates a customer. Needs a company or a last name and a full address (line 1, postal code, city, country).",
+    inputSchema: { ...customerFields, address },
+    annotations: WRITE,
+}, ({ address, ...fields }) => respond(() => client.post("/customers", { ...fields, address_attributes: address })));
+server.registerTool("update_customer", {
+    title: "Update a customer",
+    description: "Changes the given fields of a customer; fields that are left out stay as they are.",
+    inputSchema: { id: z.number().int(), ...customerFields, address: address.partial().optional() },
+    annotations: { ...WRITE, idempotentHint: true },
+}, ({ id, address, ...fields }) => respond(() => client.patch(`/customers/${id}`, { ...fields, ...(address && { address_attributes: address }) })));
+server.registerTool("create_invoice", {
+    title: "Create a draft invoice",
+    description: "Creates a draft invoice for a customer. Number, language, texts and VAT treatment come from the account settings. " +
+        "The invoice is not sent; it counts towards the monthly invoice maximum of the plan.",
+    inputSchema: { customer_id: z.number().int(), items: z.array(item).min(1), ...invoiceFields },
+    annotations: WRITE,
+}, (input) => respond(async () => withInvoiceLinks(await client.post("/invoices", input))));
+server.registerTool("update_invoice", {
+    title: "Update a draft invoice",
+    description: "Changes a draft invoice. Passing items replaces all existing items, so send the complete list. Sent invoices cannot be changed.",
+    inputSchema: { id: z.number().int(), items: z.array(item).min(1).optional(), ...invoiceFields },
+    annotations: { ...WRITE, idempotentHint: true },
+}, ({ id, ...changes }) => respond(async () => withInvoiceLinks(await client.patch(`/invoices/${id}`, changes))));
+server.registerTool("list_invoices", {
+    title: "List invoices",
+    description: "Lists invoices, newest first. Status: draft, open (sent and unpaid), overdue (open and past due) or paid.",
+    inputSchema: {
+        status: z.enum(["draft", "open", "overdue", "paid"]).optional(),
+        customer_id: z.number().int().optional(),
+        number: z.string().optional(),
+        after: date.optional().describe("Invoice date from"),
+        before: date.optional().describe("Invoice date until"),
+        page,
+        per_page: z.number().int().min(1).max(100).optional(),
+    },
+    annotations: READ,
+}, (filters) => respond(async () => withInvoiceLinks(await client.get("/invoices", filters))));
+server.registerTool("get_invoice", {
+    title: "Get an invoice",
+    description: "Returns one invoice with its items, amounts and payment status.",
+    inputSchema: { id: z.number().int() },
+    annotations: READ,
+}, ({ id }) => respond(async () => withInvoiceLinks(await client.get(`/invoices/${id}`))));
+server.registerTool("download_invoice", {
+    title: "Download an invoice file",
+    description: "Saves the PDF or the XML e-invoice of an invoice on this computer and returns the file path. " +
+        "Defaults to the Downloads folder.",
+    inputSchema: {
+        id: z.number().int(),
+        format: z.enum(["pdf", "xml"]).default("pdf"),
+        directory: z.string().optional().describe("Target folder, defaults to ~/Downloads"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ id, format, directory }) => respond(async () => {
+    const file = await client.getFile(`/invoices/${id}.${format}`);
+    const folder = directory ?? path.join(homedir(), "Downloads");
+    await mkdir(folder, { recursive: true });
+    const target = path.join(folder, path.basename(file.filename));
+    await writeFile(target, file.data);
+    return `Saved to ${target}`;
+}));
+server.registerTool("record_payment", {
+    title: "Record a payment",
+    description: "Records a payment for one or more sent, open invoices of the same customer and tax rate. The amount is gross.",
+    inputSchema: {
+        invoice_ids: z.array(z.number().int()).min(1),
+        amount: z.number().positive().describe("Gross amount received"),
+        payment_method: z.enum(["transfer", "cash"]).optional().describe("Defaults to transfer"),
+        date: date.optional().describe("Defaults to today"),
+    },
+    annotations: WRITE,
+}, (input) => respond(() => client.post("/payments", input)));
+server.registerTool("list_payments", {
+    title: "List payments",
+    description: "Lists recorded payments, newest first, optionally only those for one invoice.",
+    inputSchema: { invoice_id: z.number().int().optional(), page },
+    annotations: READ,
+}, (filters) => respond(() => client.get("/payments", filters)));
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "billingengine-mcp",
+  "mcpName": "com.billingengine/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for BillingEngine: create customers and invoices, look up invoices and record payments from Claude, Cursor and other MCP clients.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "invoicing",
+    "invoice",
+    "e-invoice",
+    "billingengine",
+    "xrechnung",
+    "zugferd"
+  ],
+  "homepage": "https://www.billingengine.com/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/billingengine/billingengine-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/billingengine/billingengine-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Timo Kleemann",
+  "type": "module",
+  "bin": {
+    "billingengine-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  }
+}