moneybird-mcp

Ein Model Context Protocol-Server für die Buchhaltungs-API von Moneybird.

Er stellt Moneybird als eine Reihe von MCP-Tools bereit, sodass ein Assistent wie Claude Kontakte nachschlagen, Rechnungen lesen, Bankbewegungen prüfen, Zeiten erfassen und Berichte aus deiner Administration abrufen kann. Der Zugriff ist schreibgeschützt, bis du das Schreiben aktivierst. Die Tools sind in Toolsets gruppiert, die du einzeln aktivieren kannst, und der Client passt das Tempo seiner eigenen Anfragen an, um innerhalb des Moneybird-Ratenlimits zu bleiben. Er spricht stdio für lokale Clients und Streamable HTTP für entfernte Clients.

Schnellstart

Registriere den Server bei deinem Client. Für Claude Code:

claude mcp add moneybird -- npx -y moneybird-mcp serve

Bitte dann deinen Assistenten, sich zu verbinden. Der Server startet ohne Anmeldedaten und stellt ein connect_moneybird-Tool bereit: Es öffnet die Token-Seite von Moneybird in deinem Browser, fragt nach dem Token, das du dort erstellst, verifiziert es, wählt deine Administration aus und speichert sie — ohne das Gespräch zu verlassen.

Das erfordert einen Client, der MCP-Elicitation unterstützt. Wo das nicht verfügbar ist, läuft dieselbe Einrichtung in einem Terminal:

npx moneybird-mcp login

Das führt dich durch dieselben Schritte und speichert das Ergebnis in ~/.config/moneybird-mcp/credentials.json.

Prüfe, dass alles funktioniert, bevor du dich darauf verlässt:

npx moneybird-mcp status

status gibt die aktivierten Toolsets, die Schreib- und Lösch-Einstellungen, die Herkunft der Anmeldedaten und die Administrationen aus, die der Token erreichen kann. Er beendet sich mit einem Fehlercode ungleich null, wenn er Moneybird nicht erreichen kann.

Related MCP server: kalender.digital MCP Server

Authentifizierung

Moneybird bietet zwei Möglichkeiten, ein Token zu erhalten, und dieser Server unterstützt beide. Keine der beiden läuft völlig ohne Zutun ab: Moneybird implementiert weder Dynamic Client Registration noch PKCE, daher gibt es keinen Ablauf, der das Erstellen eines Tokens oder das Registrieren einer Anwendung überspringt. Das ist eine Einschränkung der Moneybird-API, nicht dieses Servers. Das connect_moneybird-Tool entfernt jeden Schritt um diesen einen herum — es öffnet die richtige Seite und erfasst das Ergebnis für dich.

Persönlicher API-Token. Du erstellst es selbst unter https://moneybird.com/user/applications/new, wählst die gewünschten Scopes aus und fügst es in moneybird-mcp login ein. Der einfachste Weg. Die Scopes sind bei der Erstellung festgelegt, und Moneybird lässt diese Tokens derzeit nicht ablaufen — was auch bedeutet, dass eines nicht automatisch rotiert werden kann. Behandle es wie ein Passwort.

OAuth-Anwendung. Du registrierst eine Anwendung an derselben Stelle, dann:

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

Der Server öffnet die Autorisierungsseite von Moneybird, fängt die Weiterleitung auf http://127.0.0.1:51739/callback ab und tauscht den Code um. Moneybird gleicht Redirect-URIs exakt ab, daher muss diese URI exakt so bei deiner Anwendung registriert sein. Verwende --port, um eine andere zu wählen, oder --oob, damit Moneybird den Code im Browser anzeigt, statt weiterzuleiten — nützlich, wenn kein Loopback-Listener geöffnet werden kann. OAuth-Tokens können bei Moneybird widerrufen und automatisch erneuert werden, wenn sie ein Ablaufdatum tragen.

Um ein Token ohne jede Rückfrage zu speichern, zum Beispiel in einem Provisioning-Skript:

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout entfernt die gespeicherte Datei. Bei einer OAuth-Anmeldung widerruft es die Autorisierung selbst nicht — das erledigst du in Moneybird.

Siehe docs/authentication.md für Scopes, Erneuerungsverhalten und die genauen Abläufe.

Konfiguration

Die Konfiguration kommt aus der Umgebung; CLI-Flags überschreiben sie.

Umgebungsvariablen

Befehle

Flags

Toolsets

Die Tools sind nach den eigenen Domänen von Moneybird gruppiert. Fünf sind standardmäßig aktiviert; die anderen vier sind Opt-in.

Lege sie explizit fest, ergänze die Standardeinstellungen oder ziehe davon ab:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

Ein -name-Eintrag an beliebiger Stelle der Liste bedeutet, dass die Liste von den Standardeinstellungen ausgeht statt von nichts. all hat Vorrang vor allem anderen. Ein unbekannter Name ist ein Fehler, kein stiller No-op.

Die vollständige Auflistung pro Tool findest du in docs/tools.md, oder führe moneybird-mcp tools aus.

Sicherheitsmodell

Jedes Tool deklariert eine von drei Zugriffsstufen, und der Server registriert nur diejenigen, die die aktuellen Einstellungen erlauben. Ein Tool, das nicht registriert ist, ist für das Modell unsichtbar — es kann nicht aus Versehen aufgerufen oder herbeigeredet werden.

• read — immer registriert.

• write — erstellt oder ändert Daten. Benötigt --allow-write oder MONEYBIRD_ALLOW_WRITE=true.

• destroy — benötigt --allow-delete und --allow-write. --allow-delete allein bewirkt nichts.

Das Löschen ist getrennt vom Schreiben abgesichert, weil die beiden Fehlerarten nicht vergleichbar sind. Ein falscher Schreibvorgang hinterlässt einen Datensatz, den du korrigieren kannst; ein Löschen oder eine an einen Kunden gesendete Rechnung kann die API nicht rückgängig machen. Schreibzugriff zu aktivieren, damit ein Assistent eine Rechnung entwerfen kann, sollte ihm nicht auch erlauben, deine Buchhaltung zu entfernen. Die Stufe destroy umfasst daher sowohl Löschungen als auch Aufrufe, die in der Praxis unumkehrbar sind, etwa das Senden eines Dokuments an einen Kontakt.

Nur-Lesen ist die Standardeinstellung. Aktiviere nur das Nötigste:

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

Client-Einrichtung

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

Mit Schreibzugriff und einer größeren Auswahl an Tools:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

Füge den Server zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

Die Datei befindet sich unter ~/Library/Application Support/Claude/claude_desktop_config.json auf macOS und %APPDATA%\Claude\claude_desktop_config.json auf Windows. Starte die App nach dem Bearbeiten neu.

Beliebiger stdio-Client

Der Server ist ein einfacher stdio-MCP-Server. Führe moneybird-mcp serve aus und kommuniziere per JSON-RPC über stdin und stdout. Diagnosemeldungen gehen an stderr, niemals an stdout.

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

Wenn du Zugangsdaten lieber nicht auf der Festplatte speichern möchtest, setze MONEYBIRD_API_TOKEN im env-Block des Clients. Er hat Vorrang vor allem, was in credentials.json steht.

Docker und Self-Hosting

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

Das Image verwendet standardmäßig den HTTP-Transport auf 0.0.0.0:3000 und stellt /mcp sowie ein nicht authentifiziertes /healthz bereit. Betreibe es ohne Authentifizierung nicht unter einer öffentlichen Adresse.

docs/hosting.md behandelt die drei HTTP-Authentifizierungsmodi, Multi-Tenant-passthrough-Bereitstellungen, Hinweise zu Reverse-Proxys und das Verbinden eines entfernten Clients.

Rate-Limits

Moneybird erlaubt 150 Anfragen pro 5 Minuten pro IP und 50 pro 5 Minuten für /reports-Endpunkte. Der Client führt für beide Budgets eigene Gleitfenster-Zähler und verzögert eine Anfrage, die eines davon überschreiten würde, sodass bei normaler Nutzung keine 429s auftreten. Wenn Moneybird dennoch eine 429 zurückgibt, respektiert der Client Retry-After und verwendet andernfalls exponentielles Backoff mit vollem Jitter, bis zu MONEYBIRD_MAX_RETRIES Versuchen.

Das Budget gilt pro IP, nicht pro Token. Mehrere Instanzen hinter einer gemeinsamen ausgehenden Adresse teilen es sich, und die lokalen Zähler können einander nicht sehen. Bemesse die Bereitstellungen entsprechend.

Entwicklung

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md wird aus den Tool-Definitionen generiert. Generiere sie nach dem Hinzufügen oder Ändern eines Tools neu:

npm run docs:tools

spec/endpoints.json fixiert die veröffentlichte Operationsliste von Moneybird, und ein Test prüft jeden Pfad, den ein Tool aufruft, gegen diese Liste. Aktualisiere sie, wenn Moneybird API-Änderungen veröffentlicht:

npm run spec:refresh
npm test

Ein fehlschlagender Endpunkt-Test nach einer Aktualisierung bedeutet, dass eine Route, von der ein Tool abhängt, verschoben oder zurückgezogen wurde.

Mitwirken

Issues und Pull-Requests sind unter https://github.com/HalloSouf/moneybird-mcp willkommen. Bitte führe vor dem Eröffnen eines Pull-Requests npm run typecheck, npm test und npm run format:check aus; CI führt dieselben Prüfungen auf Node 20 und 22 durch.

Lizenz

MIT. Siehe LICENSE.