MCP-Server

Der Frihet MCP-Server implementiert das Model Context Protocol, damit KI-Assistenten direkt mit Ihrem ERP interagieren können. Rechnungen erstellen, Ausgaben erfassen, Kunden abfragen oder Angebote verwalten – alles von Ihrer IDE oder Ihrem Terminal aus, in natürlicher Sprache.

Sie:      "Erstellen Sie eine Rechnung für TechStart SL, 40 Stunden Beratung zu 75 EUR/Stunde, Fälligkeit 1. März"
Claude:  Erledigt. Rechnung INV-2026-089 erstellt. Gesamt: 3.000,00 EUR + 21% MwSt. = 3.630,00 EUR.

Was Sie erwarten können (und was nicht)

Der MCP-Server ist eine zustandslose Brücke zwischen Ihrem KI-Assistenten und der Frihet REST-API. Jeder Tool-Aufruf wird in eine HTTP-Anfrage an die API übersetzt.

Was er KANN:

Vollständiges CRUD für Rechnungen, Ausgaben, Kunden, Produkte, Angebote und Webhooks
Suche nach Rechnungen nach Kundenname
Zugriff auf Referenzdaten (Steuersätze, Steuerkalender, Kategorien)
Geführte Workflows (Monatsabschluss, Steuervorbereitung, Mahnwesen)

Was er NICHT kann:

OCR von Dokumenten (das erledigt der KI-Assistent innerhalb der App)
PDF-Generierung (nutzen Sie die REST-API direkt: GET /v1/invoices/:id/pdf)
Zahlungsabwicklung (Zahlungseingänge werden über Stripe Connect in der App verwaltet)

Voraussetzungen

Frihet-Konto mit API-Zugriff (kostenpflichtige Pläne)
API-Schlüssel, generiert über das Dashboard

API-Schlüssel erhalten

Melden Sie sich bei app.frihet.io an
Gehen Sie zu Einstellungen > Entwickler > API-Schlüssel
Klicken Sie auf API-Schlüssel erstellen
Kopieren Sie den Schlüssel (beginnt mit fri_) – er wird nur einmal angezeigt

Installation

Universal (30+ Agenten)

Der schnellste Weg, den MCP-Server und den Business-Skill zu installieren:

npx skills add Frihet-io/frihet-mcp

Funktioniert mit Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code und 30+ weiteren Agenten.

MCP Registry

Der Server ist als io.frihet/erp in der offiziellen MCP Registry registriert. MCP-Clients, die die Registry unterstützen, können ihn automatisch über seinen kanonischen Namen entdecken und installieren.

Direkter npx-Aufruf

npx -y @frihet/mcp-server@latest

Sie müssen nichts global installieren. npx lädt die neueste Version automatisch herunter und führt sie aus.

Manuelle Konfiguration

Es gibt zwei Verbindungsmodi: lokal (der Server läuft auf Ihrem Rechner über npx) und remote (direkte Verbindung zu mcp.frihet.io, ohne Installation).

Lokal (stdio)

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server@latest"],
      "env": {
        "FRIHET_API_KEY": "fri_tu_clave_aqui"
      }
    }
  }
}

Remote (streamable-http)

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_tu_clave_aqui"
      }
    }
  }
}

Konfiguration pro Client

Die JSON-Struktur ist bei allen Clients identisch. Es ändert sich lediglich der Speicherort der Konfigurationsdatei.

Client	Konfigurationsdatei
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` oder `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	VS Code Konfiguration oder `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (MCP-Sektion)

tipp

Wenn Sie Claude Code verwenden, können Sie den Server mit einem einzigen Befehl hinzufügen:

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Konfigurieren Sie anschließend die Variable FRIHET_API_KEY in der resultierenden Datei ~/.claude/mcp.json.

Umgebungsvariablen

Variable	Erforderlich	Standardwert
`FRIHET_API_KEY`	Ja	--
`FRIHET_API_URL`	Nein	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	Nein	`0`

FRIHET_API_URL ist nützlich, wenn Sie auf eine Staging-Umgebung oder eine benutzerdefinierte Instanz zeigen. Es muss https:// mit einem Hostnamen unter frihet.io sein.
FRIHET_MCP_DEBUG=1 aktiviert Debug-Level-Logs (nützlich zur Diagnose von Problemen).

OAuth-Flow

Der MCP-Server unterstützt neben der manuellen API-Schlüssel-Authentifizierung auch OAuth. Wenn ein MCP-Client den OAuth-Flow initiiert:

Der Benutzer authentifiziert sich über Firebase Auth (E-Mail, Google, GitHub oder Microsoft)
Der Client sendet das Sitzungstoken an POST /api/oauth/api-key
Der Server stellt einen neuen Schlüssel fri_xxx... mit der Bezeichnung „MCP OAuth“ und einer Gültigkeit von 365 Tagen bereit
Der Schlüssel wird automatisch für nachfolgende Aufrufe verwendet

Dies ermöglicht es Benutzern, den MCP-Server zu verbinden, ohne Schlüssel manuell kopieren zu müssen.

Verfügbare Tools (44)

Der Server stellt 52 Tools zur Verfügung, die in 7 Kategorien organisiert sind. Jedes Tool enthält eine strukturierte Ausgabe (outputSchema + structuredContent), damit Assistenten Antworten zuverlässig parsen können, sowie Sicherheits- und Inhaltsanmerkungen. Zweisprachig (EN/ES).

Rechnungen (6 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_invoices`	Listet Rechnungen mit Paginierung auf	`limit`, `offset`
`get_invoice`	Ruft eine Rechnung anhand der ID ab	`id`
`create_invoice`	Erstellt eine Rechnung mit Detailpositionen	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Aktualisiert Felder einer Rechnung (teilweise)	`id`, und jedes zu ändernde Feld
`delete_invoice`	Löscht eine Rechnung dauerhaft	`id`
`search_invoices`	Sucht Rechnungen nach Kundenname	`clientName`, `limit`, `offset`

Mögliche Rechnungsstatus: draft, sent, paid, overdue, cancelled

Ausgaben (5 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_expenses`	Listet Ausgaben mit Paginierung auf	`limit`, `offset`
`get_expense`	Ruft eine Ausgabe anhand der ID ab	`id`
`create_expense`	Erfasst eine neue Ausgabe	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Ändert eine bestehende Ausgabe (teilweise)	`id`, und jedes zu ändernde Feld
`delete_expense`	Löscht eine Ausgabe dauerhaft	`id`

Kunden (5 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_clients`	Listet alle Kunden auf	`limit`, `offset`
`get_client`	Ruft einen Kunden anhand der ID ab	`id`
`create_client`	Erfasst einen neuen Kunden	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Aktualisiert Kundendaten (teilweise)	`id`, und jedes zu ändernde Feld
`delete_client`	Löscht einen Kunden dauerhaft	`id`

Produkte (5 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_products`	Listet Produkte und Dienstleistungen auf	`limit`, `offset`
`get_product`	Ruft ein Produkt anhand der ID ab	`id`
`create_product`	Erstellt ein Produkt oder eine Dienstleistung	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Ändert ein bestehendes Produkt (teilweise)	`id`, und jedes zu ändernde Feld
`delete_product`	Löscht ein Produkt dauerhaft	`id`

Angebote (5 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_quotes`	Listet Angebote auf	`limit`, `offset`
`get_quote`	Ruft ein Angebot anhand der ID ab	`id`
`create_quote`	Erstellt ein Angebot für einen Kunden	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Ändert ein Angebot (teilweise)	`id`, und jedes zu ändernde Feld
`delete_quote`	Löscht ein Angebot dauerhaft	`id`

Mögliche Angebotsstatus: draft, sent, accepted, rejected, expired

Webhooks (5 Tools)

Tool	Beschreibung	Schlüsselparameter
`list_webhooks`	Listet konfigurierte Webhooks auf	`limit`, `offset`
`get_webhook`	Ruft die Konfiguration eines Webhooks ab	`id`
`create_webhook`	Registriert einen Webhook-Endpoint	`url`, `events[]`, `active`, `secret`
`update_webhook`	Ändert einen bestehenden Webhook	`id`, und jedes zu ändernde Feld
`delete_webhook`	Löscht einen Webhook dauerhaft	`id`

Verfügbare Webhook-Ereignisse: invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Siehe Webhooks für das Payload-Format und die HMAC-Verifizierung.

Verfügbare Ressourcen (8)

MCP-Ressourcen sind Referenzdaten, die der Assistent abrufen kann, ohne API-Aufrufe tätigen zu müssen. Sie sind statisch und immer zugänglich.

Ressource	URI	Beschreibung
API-Schema	`frihet://api/schema`	Übersicht über Endpoints, Authentifizierung, Rate Limits und Fehlercodes
Steuersätze	`frihet://tax/rates`	MwSt. (21/10/4%), IGIC (7/3/0%), IPSI, innergemeinschaftlich, Einkommensteuer (15%/7%)
Steuerkalender	`frihet://tax/calendar`	Vierteljährliche Einreichungsfristen (Modell 303, 130, 420, 390)
Ausgabenkategorien	`frihet://config/expense-categories`	8 Kategorien mit Abzugsfähigkeitsregeln und steuerlicher Behandlung
Rechnungsstatus	`frihet://config/invoice-statuses`	Statusfluss (Entwurf, gesendet, bezahlt, überfällig, storniert) mit Triggern
Lieferanten	`frihet://config/vendors`	Liste der registrierten Lieferanten mit Steuer- und Kontaktdaten
Aktive Integrationen	`frihet://config/integrations`	Status der verbundenen Integrationen (Stripe, Shopify usw.)
Geschäftskonfiguration	`frihet://config/business`	Steuerdaten des Unternehmens, Steuerzone, Währung und Präferenzen

Verfügbare Prompts (7)

Prompts sind geführte Workflows, die der Assistent Schritt für Schritt ausführt. Sie werden nach Namen aufgerufen.

Prompt	Beschreibung	Parameter
`monthly-close`	Monatsabschluss: Überprüft unbezahlte Rechnungen, kategorisiert Ausgaben, prüft Steuerpflichten, erstellt eine Zusammenfassung	`month` (optional)
`onboard-client`	Kunden-Onboarding: Ermittelt den Steuersatz basierend auf dem Standort, erstellt einen Eintrag, generiert ein Willkommensangebot	`clientName`, `country`, `region`
`quarterly-tax-prep`	Quartals-Steuervorbereitung: Sammelt Rechnungen, berechnet MwSt./IGIC, generiert eine Vorschau der Modelle 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Mahnwesen: Identifiziert überfällige Rechnungen, gruppiert nach Kunden, formuliert Mahnschreiben	—
`expense-batch`	Ausgaben-Stapelverarbeitung: Kategorisiert, wendet Steuern an, prüft Abzugsfähigkeit, erstellt mit Bestätigung	`fiscalZone`
`vendor-analysis`	Lieferantenanalyse: Gruppiert Ausgaben nach Lieferanten, berechnet Summen, identifiziert Trends und Einsparpotenziale	`period` (optional)
`business-health`	Geschäftsgesundheit: Wichtige KPIs, Vergleich zum Vormonat, Warnungen und umsetzbare Empfehlungen	`month` (optional)

tipp

Sie können einen Prompt direkt aufrufen: "Führen Sie den Monatsabschluss für Februar aus" oder "Bereiten Sie die Steuern für Q1 vor".

Anwendungsbeispiele

Dies sind reale Anfragen in natürlicher Sprache, die der Assistent in MCP-Tool-Aufrufe übersetzt.

Eine Rechnung erstellen

"Erstellen Sie eine Rechnung für Acme SL mit 10 Stunden Beratung zu 95 EUR/Stunde, Fälligkeit 15. März"

Der Assistent ruft create_invoice mit clientName: "Acme SL", einer Detailposition (10 x 95) und dueDate: "2026-03-15" auf. Er berechnet den Gesamtbetrag automatisch.

Eine Ausgabe erfassen

"Erfassen Sie eine Ausgabe von 59.99 EUR für Adobe Creative Cloud, Kategorie Software, abzugsfähig"

Ruft create_expense mit description, amount: 59.99, category: "software" und taxDeductible: true auf.

Rechnungen eines Kunden suchen

"Suchen Sie alle Rechnungen von TechStart SL"

Ruft search_invoices mit clientName: "TechStart SL" auf und gibt die Übereinstimmungen mit ihren Gesamtsummen und Status zurück.

Überfällige Rechnungen abfragen

"Zeigen Sie mir alle unbezahlten Rechnungen"

Ruft list_invoices auf und filtert nach status: "sent" oder "overdue", wobei die überfälligen Rechnungen nach Betrag sortiert angezeigt werden.

Einen Kunden anlegen

"Neuer Kunde: Design Studio SL, NIF B87654321, E-Mail hola@designstudio.es, Madrid 28001"

Ruft create_client mit Name, NIF, E-Mail und Adresse auf.

Automatisierung konfigurieren

"Erstellen Sie einen Webhook, um https://meine-app.com/hook zu benachrichtigen, wenn eine Rechnung bezahlt wird"

Ruft create_webhook mit url und events: ["invoice.paid"] auf.

Ein Produkt aktualisieren

"Erhöhen Sie den Preis für die Beratungsstunde auf 85 EUR"

Ruft update_product mit der Produkt-ID und unitPrice: 85 auf. Es wird nur das angegebene Feld geändert.

Beobachtbarkeit

Der MCP-Server v1.5.1 umfasst strukturiertes Logging und Tool-Metriken.

Strukturiertes Logging

Alle Logs werden als JSON an stderr ausgegeben (MCP verwendet stdout für Protokollnachrichten). Jeder Eintrag enthält:

level: debug, info, warn, error
service: immer frihet-mcp
timestamp: ISO 8601
tool: Name des Tools (falls zutreffend)
operation: Art des Vorgangs (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs: Ausführungszeit in Millisekunden
error: Fehlerdetails (message, code, statusCode)

Aktivieren Sie die Debug-Logs mit FRIHET_MCP_DEBUG=1.

Tool-Metriken

Der Server protokolliert im Speicher die Aufrufe jedes Tools: Anzahl der Aufrufe, Fehler und durchschnittliche Dauer. Beim Herunterfahren des Servers (SIGINT/SIGTERM) wird eine Zusammenfassung ausgegeben:

{
  "level": "info",
  "message": "Herunterfahren nach 3600s – 42 Aufrufe, 1 Fehler",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Automatische Rate-Limit-Wiederholung

Wenn die API mit 429 antwortet, versucht der Server automatisch mit exponentiellem Backoff erneut (bis zu 3 Wiederholungen). Die Wiederholungen werden im Log protokolliert:

{
  "level": "warn",
  "message": "Rate limitiert, GET /invoices wird erneut versucht (Versuch 2, Verzögerung 2000ms)",
  "operation": "api_retry"
}

Sie müssen das Rate Limiting nicht manuell verwalten – der Server übernimmt das für Sie.

Transport

Der Frihet MCP-Server unterstützt zwei Transportmodi. Beide stellen dieselben 52 Tools, 11 Ressourcen und 10 Prompts zur Verfügung.

Lokal (stdio)

Der Server läuft als lokaler Prozess auf Ihrem Rechner. Die Kommunikation zwischen dem MCP-Client und dem Server erfolgt über Standard-Ein-/Ausgabe (stdin/stdout).

Erfordert: Node.js installiert (wird automatisch über npx heruntergeladen)
Vorteil: Geringere Latenz, funktioniert ohne Internetverbindung (außer für API-Aufrufe)
Anwendungsfall: Tägliche Entwicklung, intensive Nutzung, Unternehmensumgebungen mit Netzwerkbeschränkungen

Remote (streamable-http)

Der Server läuft auf Cloudflare Workers. Ihr MCP-Client verbindet sich direkt mit https://mcp.frihet.io/mcp über HTTP.

Erfordert: Nur Internetverbindung
Vorteil: Keine lokale Installation, keine Abhängigkeiten, funktioniert auf jedem Gerät
Anwendungsfall: Schnelle Konfiguration, Teams, die keine Pakete installieren möchten, Clients, die nur HTTP-Transport unterstützen

info

Wenn Ihr MCP-Client streamable-http nicht unterstützt (einige ältere Clients unterstützen nur stdio), verwenden Sie den lokalen Modus.

Fehlerbehandlung

Rate Limiting

Die API erlaubt 100 Anfragen pro Minute pro Schlüssel. Wenn das Limit überschritten wird, gibt der Server einen 429-Fehler mit der Wartezeit in retryAfter zurück.

Der MCP-Server verwaltet das Rate Limiting automatisch mit exponentiellem Backoff: er versucht die Anfrage nach der angegebenen Wartezeit erneut, ohne Benutzereingriff. Maximal 3 Wiederholungen.

Authentifizierungsfehler

Code	Ursache	Lösung
`401`	Ungültiger, abgelaufener oder nicht angegebener API-Schlüssel	Überprüfen Sie, ob der Schlüssel in Ihrer Konfiguration mit `fri_` beginnt und nicht abgelaufen ist
`403`	Der Schlüssel hat keine Berechtigungen für diese Ressource	Generieren Sie einen neuen Schlüssel mit den erforderlichen Berechtigungen

Andere Fehler

Code	Beschreibung
`400`	Falsche Parameter oder fehlende Pflichtfelder
`404`	Die angeforderte Ressource existiert nicht
`408`	Anfrage-Timeout (30 Sekunden)
`413`	Der Anfragekörper überschreitet 1 MB
`422`	Gültige, aber nicht verarbeitbare Daten (z. B. Steuerprofil nicht konfiguriert)
`429`	Anfragelimit überschritten (wird automatisch erneut versucht)
`500`	Interner Serverfehler

Alle Fehler geben eine beschreibende zweisprachige (EN/ES) Nachricht zurück, damit der Assistent das Problem dem Benutzer klar mitteilen kann.

Limits

Konzept	Wert
Anfragen pro Minute	100 pro API-Schlüssel
Ergebnisse pro Seite	Maximal 100 (Standard 50)
Anfragekörper	Maximal 1 MB
Webhook-Payload	Maximal 100 KB
Webhooks pro Konto	Maximal 20
Anfrage-Timeout	30 Sekunden
Wiederholungen bei Rate Limit	Maximal 3

Unterschied zur REST-API

	MCP-Server	REST-API
Gerichtet an	KI-Assistenten (Claude, Cursor, Windsurf)	Anwendungen, Skripte, Integrationen
Kommunikation	Natürliche Sprache über den MCP-Client	Direkt HTTP/JSON
Authentifizierung	Umgebungsvariable in der Client-Konfiguration (oder OAuth)	Header `X-API-Key` oder `Authorization: Bearer`
Format	Formatierter Text + strukturierte Ausgabe für den Assistenten	Rohes JSON
Rate Limiting	Automatisch verwaltet (exponentieller Backoff, 3 Wiederholungen)	Manuell (der Consumer muss Wiederholungen implementieren)
Beobachtbarkeit	Strukturiertes Logging + Metriken pro Tool	Anfragelogs über `X-Request-Id`
Anwendungsfall	Mit Ihrem ERP aus der IDE sprechen	Programmgesteuerte Integrationen erstellen

Intern übersetzt der MCP-Server jeden Tool-Aufruf in eine Anfrage an die REST-API. Er dupliziert keine Logik – er ist eine zustandslose Brücke.

Entwicklung

Um beizutragen oder den Server im Entwicklungsmodus auszuführen:

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Lokal ausführen:

FRIHET_API_KEY=fri_tu_clave node dist/index.js

Mit Debug-Logs ausführen:

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js

Mit dem MCP Inspector testen:

npx @modelcontextprotocol/inspector node dist/index.js

Was Sie erwarten können (und was nicht)​

Voraussetzungen​

API-Schlüssel erhalten​

Installation​

Universal (30+ Agenten)​

MCP Registry​

Direkter npx-Aufruf​

Manuelle Konfiguration​

Lokal (stdio)​

Remote (streamable-http)​

Konfiguration pro Client​

Umgebungsvariablen​

OAuth-Flow​

Verfügbare Tools (44)​

Rechnungen (6 Tools)​

Ausgaben (5 Tools)​

Kunden (5 Tools)​

Produkte (5 Tools)​

Angebote (5 Tools)​

Webhooks (5 Tools)​

Verfügbare Ressourcen (8)​

Verfügbare Prompts (7)​

Anwendungsbeispiele​

Eine Rechnung erstellen​

Eine Ausgabe erfassen​

Rechnungen eines Kunden suchen​

Überfällige Rechnungen abfragen​

Einen Kunden anlegen​

Automatisierung konfigurieren​

Ein Produkt aktualisieren​

Beobachtbarkeit​

Strukturiertes Logging​

Tool-Metriken​

Automatische Rate-Limit-Wiederholung​

Transport​

Lokal (stdio)​

Remote (streamable-http)​

Fehlerbehandlung​

Rate Limiting​

Authentifizierungsfehler​

Andere Fehler​

Limits​

Unterschied zur REST-API​

Entwicklung​

Verwandte Ressourcen​

Was Sie erwarten können (und was nicht)

Voraussetzungen

API-Schlüssel erhalten

Installation

Universal (30+ Agenten)

MCP Registry

Direkter npx-Aufruf

Manuelle Konfiguration

Lokal (stdio)

Remote (streamable-http)

Konfiguration pro Client

Umgebungsvariablen

OAuth-Flow

Verfügbare Tools (44)

Rechnungen (6 Tools)

Ausgaben (5 Tools)

Kunden (5 Tools)

Produkte (5 Tools)

Angebote (5 Tools)

Webhooks (5 Tools)

Verfügbare Ressourcen (8)

Verfügbare Prompts (7)

Anwendungsbeispiele

Eine Rechnung erstellen

Eine Ausgabe erfassen

Rechnungen eines Kunden suchen

Überfällige Rechnungen abfragen

Einen Kunden anlegen

Automatisierung konfigurieren

Ein Produkt aktualisieren

Beobachtbarkeit

Strukturiertes Logging

Tool-Metriken

Automatische Rate-Limit-Wiederholung

Transport

Lokal (stdio)

Remote (streamable-http)

Fehlerbehandlung

Rate Limiting

Authentifizierungsfehler

Andere Fehler

Limits

Unterschied zur REST-API

Entwicklung

Verwandte Ressourcen