bokio-mcp

Ein MCP-Server für die Bokio-Buchhaltungs-API. Er stellt 85 Tools für ein Bokio-Unternehmen bereit – Rechnungen, Kunden, Lieferanten, Lieferantenrechnungen, Journalbuchungen, Gutschriften, Kontenplan, Geschäftsjahre, Artikel, Tags, Uploads, SIE-Export und Bankzahlungen – sodass ein MCP-Client Ihre Buchhaltung lesen und (optional) schreiben kann.

Keine Konten, keine Datenbank, kein gehosteter Dienst. Ein Unternehmen pro Serverinstanz.

"Which invoices are still unpaid?"
"Book the attached receipt against account 6570."
"Export the SIE file for the 2025 fiscal year."

Schnellstart

Testen Sie es mit Fixtures, ohne Bokio-Konto:

BOKIO_MOCK=true npx bokio-mcp status
# { "companyName": "Testbolaget AB", "status": "active", ... }

BOKIO_MOCK=true stellt ein In-Process-Fake von Bokio bereit, sodass die gesamte Tool-Oberfläche funktioniert, bevor Sie Anmeldedaten haben.

Für echte Daten wählen Sie eine der beiden Anmeldeoptionen unten und fügen Sie den Server zu Ihrem MCP-Client hinzu.

Option A – Privates Integrations-Token (empfohlen)

In Bokio: Unternehmenseinstellungen → API-Tokens → Private Integration erstellen. Das Token ist langlebig, auf dieses eine Unternehmen beschränkt und benötigt keine OAuth-Überprüfung.

{
  "mcpServers": {
    "bokio": {
      "command": "npx",
      "args": ["-y", "bokio-mcp"],
      "env": {
        "BOKIO_INTEGRATION_TOKEN": "your-token",
        "BOKIO_COMPANY_ID": "the-company-uuid-from-the-bokio-url"
      }
    }
  }
}

Option B – OAuth

Registrieren Sie eine Integration im Bokio-Entwicklerportal mit der Redirect-URI http://127.0.0.1:7337/callback und führen Sie dann Folgendes aus:

export BOKIO_CLIENT_ID=... BOKIO_CLIENT_SECRET=...
npx bokio-mcp login

Dadurch wird Bokio in Ihrem Browser geöffnet und die Tokens werden nach ~/.config/bokio-mcp/tokens.json (Modus 0600) geschrieben. Zugriffstokens werden automatisch erneuert, einschließlich Rotation des Aktualisierungstokens. Weisen Sie Ihren MCP-Client mit denselben beiden Umgebungsvariablen auf npx -y bokio-mcp an.

Related MCP server: QuickBooks Online MCP Server

Schreibzugriff ist standardmäßig deaktiviert

Eine frische Installation kann lesen, aber nicht schreiben. Verändernde Tools sind nicht nur blockiert – sie fehlen in tools/list vollständig, sodass das Modell nie eine Änderung vorschlägt, die es nicht ausführen kann:

BOKIO_ALLOW_WRITES=true

Von den 85 Tools sind 38 schreibgeschützt und 47 verändern Daten. Starten Sie ohne das Flag, prüfen Sie, dass das Modell das liest, was Sie erwarten, und aktivieren Sie dann den Schreibzugriff.

Befehle

HTTP-Transport

Für Self-Hosting, z. B. hinter einem Reverse-Proxy oder in einem Container:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) bokio-mcp serve --http

/mcp wird dann durch diesen statischen Bearer-Token geschützt. Ohne MCP_AUTH_TOKEN bindet der Server nur an 127.0.0.1, anstatt eine unauthentifizierte Brücke zu echten Buchhaltungsdaten freizugeben. Ein Dockerfile ist enthalten; es verwendet standardmäßig diesen Transport.

Umgebung

Siehe .env.example für die kommentierte Version.

Hinweis zur Token-Speicherung

Die OAuth-Token-Datei ist im Klartext mit Modus 0600, sofern BOKIO_TOKEN_ENCRYPTION_KEY nicht gesetzt ist – dieselbe Herangehensweise wie die gh- und aws-CLIs. Auf einem persönlichen Rechner bietet ein Schlüssel, der neben dem verschlüsselten Inhalt liegt, kaum zusätzlichen Schutz; setzen Sie ihn, wenn die Datei an einem weniger privaten Ort liegt, z. B. in einem Container-Image oder auf einem gemeinsam genutzten Host.

Entwicklung

npm install
npm test          # 36 tests, no database, no credentials
npm run typecheck
npm run dev       # tsx watch, stdio transport

BOKIO_MOCK=true leitet jede Bokio-Anfrage auf der Fetch-Ebene in einen In-Process-Mock um, sodass sich das Verhalten unter Stdio, unter HTTP und in Tests identisch verhält, ohne dass ein Server läuft. test/mcp.test.ts treibt das echte MCP-Protokoll Ende-zu-Ende dagegen.

Die Tool-Definitionen sind in src/tools/bokio/ handgeschrieben, aber jeder Pfad und jede Methode werden zur Compile-Zeit mithilfe des op()-Helpers gegen die OpenAPI-Spezifikation geprüft – ein Tippfehler in einer Route führt zu einem fehlgeschlagenen Build. Generieren Sie die Spezifikationstypen neu mit:

npm run gen:bokio

Nicht unterstützt

• Mehr als ein Unternehmen pro Instanz. Bokio-Anmeldedaten sind unternehmensspezifisch; führen Sie für ein zweites Unternehmen eine zweite Instanz aus.

• Erweiterte Berechtigungen. bank-payments:* erfordert eine gesonderte Freigabe durch Bokio. Die Bankzahlungs-Tools sind registriert, schlagen jedoch fehl, bis Ihre Integration freigegeben und die Bereiche zu BOKIO_SCOPES hinzugefügt wurden.

Lizenz

MIT