beleg.bot MCP Server
Verbinde Claude und andere KI-Assistenten direkt mit deinen Bewirtungsbelegen. Erstelle, suche und verwalte Belege per Spracheingabe — ohne die App zu öffnen.
POST https://beleg.bot/api/mcpJSON-RPC 2.0 · MCP 2024-11-05Beispiel-Prompts für Claude
Schnellstart
Authentifizierung
Alle Anfragen müssen einen API Key im Authorization-Header mitschicken.
Authorization: Bearer bb_a1b2c3d4e5f6...
Keys werden verschlüsselt gespeichert und können jederzeit widerrufen werden.Key generieren →
API testen (curl)
curl -s https://beleg.bot/api/mcp \
-X POST \
-H "Authorization: Bearer DEIN_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'curl -s https://beleg.bot/api/mcp \
-X POST \
-H "Authorization: Bearer DEIN_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_companies","arguments":{}},"id":2}'curl -s https://beleg.bot/api/mcp \
-X POST \
-H "Authorization: Bearer DEIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_receipt",
"arguments": {
"date": "2024-06-15",
"location": "Restaurant Flora",
"amount_gross": 48.50,
"amount_net": 40.76,
"description": "Projektbesprechung Q3-Planung",
"employee_id": "GASTGEBER_ID",
"project_id": "PROJEKT_ID",
"guest_names": "Müller, Meier"
}
},
"id": 3
}'Claude Desktop einrichten
Wähle eine der folgenden Methoden, um beleg.bot mit Claude Desktop zu verbinden.
AEmpfohlene Methode: Direktverbindung (Native SSE)
Seit März 2025 unterstützt Claude Desktop das Model Context Protocol nativ über HTTP. Dies ist die einfachste Variante: Du benötigst kein lokales Skript und kein Node.js.
Konfigurationsdatei öffnen:
~/Library/Application Support/Claude/claude_desktop_config.json{
"mcpServers": {
"belegbot": {
"type": "http",
"url": "https://beleg.bot/api/mcp",
"headers": {
"Authorization": "Bearer DEIN_API_KEY"
}
}
}
}Tipp: Ersetze DEIN_API_KEY durch deinen persönlichen Key aus dem Profil.
BAlternative: Proxy-Skript (für Bild-Uploads)
Aktuell unterstützen native HTTP-Verbindungen in Claude noch keinen direkten Datei-Upload. Wenn du beleg.bot nutzen möchtest, um lokale Bilddateien per Pfadangabe hochzuladen, nutze weiterhin das Proxy-Skript:
1. Erstelle die Datei beleg-mcp.js:
#!/usr/bin/env node
const https = require("https");
const readline = require("readline");
const fs = require("fs");
const rl = readline.createInterface({ input: process.stdin, terminal: false });
rl.on("line", (line) => {
if (!line.trim()) return;
let parsed;
try { parsed = JSON.parse(line); } catch (e) { return; }
const isNotification = parsed.id === undefined;
if (parsed?.method === "tools/call" && parsed.params?.name === "create_receipt") {
const args = parsed.params.arguments;
if (args?.local_image_path) {
try {
const ext = args.local_image_path.split(".").pop().toLowerCase();
const mimeMap = {
jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png",
gif: "image/gif", webp: "image/webp", bmp: "image/bmp",
tiff: "image/tiff", tif: "image/tiff",
heic: "image/heic", heif: "image/heif", avif: "image/avif",
pdf: "application/pdf",
};
args.local_image_base64 = fs.readFileSync(args.local_image_path).toString("base64");
args.local_image_mime = mimeMap[ext] || "image/jpeg";
args.local_image_ext = ext || "jpg";
line = JSON.stringify(parsed);
} catch (e) {
process.stderr.write(`[beleg-mcp] Bild konnte nicht gelesen werden: ${e.message}\n`);
}
}
}
const payloadBuffer = Buffer.from(line, "utf8");
const req = https.request({
hostname: "beleg.bot", path: "/api/mcp", method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer DEIN_API_KEY",
"Content-Length": payloadBuffer.length,
}
}, (res) => {
let data = "";
res.on("data", chunk => data += chunk);
res.on("end", () => {
if (isNotification) return;
process.stdout.write(data.trim() || JSON.stringify({
jsonrpc: "2.0", id: parsed.id,
error: { code: -32603, message: "Empty response from server" }
}) + "\n");
});
});
req.setTimeout(15000, () => { req.destroy(); });
req.on("error", (e) => process.stderr.write(`[beleg-mcp] Netzwerkfehler: ${e.message}\n`));
req.write(payloadBuffer);
req.end();
});2. In der claude_desktop_config.json:
{
"mcpServers": {
"belegbot": {
"command": "node",
"args": [
"/Absoluter/Pfad/zu/deiner/beleg-mcp.js"
]
}
}
}Neu: Bilder direkt aus Claude hochladen!
Claude kann Bilder per MCP normalerweise nicht anhängen. Genau dafür sorgt das obige Skript:
So geht's: Wenn du Claude bittest, einen Beleg aus einem Bild zu erstellen, ziehe nicht nur das Bild in den Chat, sondern kopiere zusätzlich den lokalen Dateipfad (z.B. /Users/name/Desktop/bon.jpg) in deine Nachricht. Dein Skript lädt das Bild dann unsichtbar im Hintergrund an beleg.bot hoch!
Tool-Referenz
Alle verfügbaren Tools mit ihren Parametern:
list_companies— Alle Firmen des Accounts auflistenKeine Parameter erforderlich
Rückgabe
Array von Firmen mit Projekt- und Kundenanzahl
create_company— Neue Firma anlegenParameter
namestringPflichtFirmennameRückgabe
Bestätigung mit ID der neuen Firma
list_projects— Projekte auflisten (optional nach Firma filtern)Parameter
companyIdstringoptionalFirmen-ID zum FilternRückgabe
Array von Projekten inkl. Firmenname
create_project— Neues Projekt unter einer Firma anlegenParameter
namestringPflichtProjektnamecompanyIdstringPflichtFirmen-IDRückgabe
Bestätigung mit ID des neuen Projekts
list_employees— Alle Gastgeber des Accounts auflistenKeine Parameter erforderlich
Rückgabe
Array von Gastgebern
create_employee— Neuen Gastgeber anlegenParameter
firstNamestringPflichtVornamelastNamestringPflichtNachnameRückgabe
Bestätigung mit ID des neuen Gastgebers
list_customers— Gäste auflisten (optional nach Firma filtern)Parameter
companyIdstringoptionalFirmen-ID zum FilternRückgabe
Array von Gästen
create_customer— Neuen Gast/Kunden unter einer Firma anlegenParameter
namestringPflichtName des Gastes/KundencompanyIdstringPflichtFirmen-IDRückgabe
Bestätigung mit ID des neuen Gastes
list_receipts— Belege auflisten mit optionalen FilternParameter
limitnumberoptionalMax. Anzahl (Standard: 20)from_datestringoptionalISO-Datum ab dem gesucht wird, z.B. 2024-01-01Rückgabe
Array von Belegen inkl. Gastgeber und Projekt
get_receipt— Einzelnen Beleg mit allen Details abrufenParameter
idstringPflichtBeleg-IDRückgabe
Beleg mit Gastgeber, Projekt, Firma und Gästen
get_pdf_url— PDF-Download-URL für einen Beleg abrufenParameter
idstringPflichtBeleg-IDRückgabe
HTTPS-URL zum PDF-Download
create_receipt— Bewirtungsbeleg manuell anlegen (ohne Foto)Parameter
datestringPflichtISO-Datum, z.B. 2024-06-15locationstringPflichtRestaurant oder Ortamount_grossnumberPflichtBruttobetrag in EURamount_netnumberPflichtNettobetrag in EURdescriptionstringoptionalGeschäftlicher Anlass (Wird sonst automatisch via KI generiert)employee_idstringPflichtGastgeber-IDproject_idstringPflichtProjekt-IDtipnumberoptionalTrinkgeld in EUR (Standard: 0)main_coursesnumberoptionalAnzahl Hauptspeisen (Standard: 1)guest_namesstringoptionalKomma-getrennte Gastnamen (Nur wenn bekannt/genannt)Rückgabe
Bestätigung mit ID und PDF-URL
Protokoll-Details
| Protokoll | JSON-RPC 2.0 über HTTPS POST |
| MCP Version | 2024-11-05 |
| Endpoint | https://beleg.bot/api/mcp |
| Auth | Bearer Token (Authorization Header) |
| Content-Type | application/json |
| Methoden | initialize · tools/list · tools/call |