MonKey Office MCP Server

MCP Server für die MonKey Office Connect JSON-API. Verbindet die Claude Desktop App mit MonKey Office, um Buchhaltungsdaten direkt abzufragen.

Claude Desktop App (Mac/PC)
        ↕  Streamable HTTP / SSE
Docker Container: monkey-office-mcp (z.B. auf NAS oder Server)
        ↕  HTTP/JSON
MonKey Office Connect (z.B. 192.168.178.53:8084)
        ↕
MonKey Office Datenbank

---

Voraussetzungen

1. MonKey Office mit Connect-Modul

• MonKey Office muss installiert und gestartet sein
• Das Connect-Modul (JSON-API) muss lizenziert und aktiviert sein
• Die Connect-API ist standardmäßig unter http://<MO-Rechner-IP>:8084/monkeyOfficeConnectJSON erreichbar

2. API-Benutzer in MonKey Office anlegen

Wichtig: Admin-User können sich nicht über die API anmelden!

1. In MonKey Office unter Verwaltung → Benutzer einen neuen Benutzer anlegen
2. Benutzername und Passwort notieren (z.B. KI / MeinPasswort)
3. Dem Benutzer die nötigen Rechte für die gewünschten Module geben

3. Docker-Umgebung

Der MCP-Server läuft als Docker Container. Du brauchst:

• Einen Rechner/NAS mit Docker und Docker Compose (z.B. QNAP Container Station, Synology, Linux-Server)
• Netzwerkzugriff vom Docker-Host auf den MonKey Office Rechner (Port 8084)
• Netzwerkzugriff von deinem Mac/PC auf den Docker-Host (Port 3000)

4. Claude Desktop App

• Claude Desktop installiert auf Mac oder Windows
• Node.js (>= 18) auf dem Mac/PC installiert (wird für mcp-remote benötigt)

---

Installation

Schritt 1: Firma-ID ermitteln

Bevor der Container gestartet wird, brauchst du die Firma_ID aus MonKey Office. Führe das einmalig von einem Rechner mit Netzwerkzugriff aus:

curl -X POST http://<MO-RECHNER-IP>:8084/monkeyOfficeConnectJSON \
  -H 'Content-Type: application/json' \
  -u 'DEIN_API_USER:DEIN_API_PASSWORT' \
  -d '{"firmaList":""}'

Die Antwort enthält eine oder mehrere Firmen mit Firma_ID:

{
  "firmaListResponse": {
    "ReturnData": {
      "FirmaListItem": [
        {
          "Firma_ID": "4F01644397CE0566C14298B4",
          "Bezeichnung": "Meine Firma GmbH"
        }
      ]
    }
  }
}

Notiere die Firma_ID der gewünschten Firma.

Schritt 2: Docker Container einrichten

Option A: Auf einem NAS/Server mit SSH

# Verzeichnis anlegen
mkdir -p /share/Container/monkey-office-mcp
cd /share/Container/monkey-office-mcp

# Dateien herunterladen
# (falls git verfügbar:)
git clone https://github.com/kustus/MO-Connect-MCP.git .

# (falls kein git: Dateien manuell kopieren – benötigt werden:
#  Dockerfile, index.js, package.json, docker-compose.yml)

Option B: QNAP Container Station GUI

1. Container Station öffnen → "Anwendung erstellen"
2. "Aus docker-compose erstellen" wählen
3. Den Inhalt der docker-compose.yml (siehe unten) einfügen
4. Erstellen klicken

Schritt 3: docker-compose.yml konfigurieren

Trage deine Zugangsdaten in die docker-compose.yml ein:

services:
  monkey-office-mcp:
    build: .
    container_name: monkey-office-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # URL zur MonKey Office Connect API
      MO_URL:       "http://<MO-RECHNER-IP>:8084/monkeyOfficeConnectJSON"
      # API-Benutzer (kein Admin!)
      MO_USER:      "DEIN_API_USER"
      MO_PASS:      "DEIN_API_PASSWORT"
      # Firma-ID aus Schritt 1
      MO_FIRMA_KEY: "DEINE_FIRMA_ID"
      PORT:         "3000"
    extra_hosts:
      - "host.docker.internal:host-gateway"

Schritt 4: Container starten

docker compose up -d --build

Schritt 5: Prüfen ob der Server läuft

curl http://<DOCKER-HOST>:3000/health

Erwartete Antwort:

{
  "status": "ok",
  "service": "monkey-office-mcp",
  "version": "1.0.0",
  "firma_key_set": true
}

---

Claude Desktop konfigurieren

Konfigurationsdatei öffnen

OS	Pfad
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

MCP-Server eintragen

Der Server wird über mcp-remote angebunden, das die Verbindung zwischen Claude Desktop (stdio) und dem Remote-Server (Streamable HTTP) herstellt:

{
  "mcpServers": {
    "monkey-office": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://<DOCKER-HOST>:3000/mcp",
        "--allow-http"
      ]
    }
  }
}

Hinweis: Ersetze <DOCKER-HOST> durch den Hostnamen oder die IP-Adresse deines NAS/Servers (z.B. 192.168.178.100 oder mein-nas).

--allow-http ist nötig, weil mcp-remote standardmäßig nur HTTPS-Verbindungen erlaubt. Im lokalen LAN ist HTTP ausreichend.

Claude Desktop neu starten

Nach dem Speichern der Konfiguration Claude Desktop komplett beenden und neu starten. Unter Einstellungen → Entwickler sollte der Server monkey-office als verbunden angezeigt werden.

---

Testen

In Claude Desktop einfach fragen:

• "Welche Firmen sind in MonKey Office verfügbar?"
• "Zeig mir alle Buchungen von Januar bis März 2026"
• "Suche Buchungen für Wüstenrot"
• "Zeig mir alle Buchungen auf Konto 4000"
• "Welche Kunden haben wir?"
• "Zeig mir die Steuersätze"
• "Welche Kostenstellen gibt es?"

---

Verfügbare Tools

Immer verfügbar

Tool	Beschreibung
firma_list	Alle Firmen/Mandanten auflisten (liefert Firma_ID)
firma_get	Firmendetails: Name, Adresse, Steuernummer, Kontenplan
buchung_list	Buchungsjournal filtern nach Zeitraum, Konto, Kostenstelle, Text
buchung_get	Einzelbuchung mit allen Journalzeilen
adresse_list	Kunden und Lieferanten suchen
adresse_get	Vollständige Adressdetails
steuersatz_list	Alle Steuersätze der Firma
kostenstellen_list	Alle Kostenstellen der Firma

Abhängig von Lizenz/Modulen

Diese Tools sind implementiert, funktionieren aber nur wenn das entsprechende MonKey Office Modul lizenziert und aktiviert ist:

Tool	Benötigtes Modul	Beschreibung
verkaufbeleg_list	Faktura	Rechnungen, Angebote, Gutschriften
verkaufbeleg_get	Faktura	Belegdetails mit Positionen
einkaufbeleg_list	Faktura	Eingangsrechnungen, Bestellungen
buchung_konto_list	Erweiterte Buchhaltung	Kontenplan auflisten
offene_posten_list	Erweiterte Buchhaltung	Offene Forderungen/Verbindlichkeiten
debitor_list	Erweiterte Buchhaltung	Debitorenkonten mit Salden
kreditor_list	Erweiterte Buchhaltung	Kreditorenkonten mit Salden
artikel_list	Faktura	Artikel und Leistungen
projekt_list	Projektverwaltung	Projekte auflisten

Falls ein Modul nicht lizenziert ist, gibt die API den Fehler "Funktion nicht implementiert" zurück.

---

Fehlerbehebung

Server "disconnected" in Claude Desktop

1. Prüfe ob der Container läuft: curl http://<DOCKER-HOST>:3000/health
2. Prüfe ob mcp-remote funktioniert: npx -y mcp-remote http://<DOCKER-HOST>:3000/mcp --allow-http
3. Stelle sicher, dass --allow-http in der Config steht (nötig für HTTP im LAN)
4. Stelle sicher, dass Node.js >= 18 installiert ist: node --version

Leere Ergebnisse bei Verkaufsbelegen

Wenn verkaufbeleg_list keine Daten zurückgibt, obwohl Rechnungen existieren: Die Rechnungen wurden möglicherweise direkt in der Buchhaltung erfasst (als Buchungen) und nicht über das Faktura-Modul erstellt. Nutze buchung_list mit suchtext um sie zu finden.

"Funktion nicht implementiert"

Diese Meldung kommt von der MonKey Office API, nicht vom MCP-Server. Das benötigte Modul ist in eurer MonKey Office Lizenz nicht enthalten oder nicht aktiviert.

Container-Logs anzeigen

docker logs monkey-office-mcp -f

---

Updates einspielen

cd /share/Container/monkey-office-mcp
git pull
docker compose up -d --build

---

Technische Details

• Transport: Streamable HTTP (/mcp) + SSE-Fallback (/sse)
• Runtime: Node.js 20 Alpine (Docker)
• API-Protokoll: MonKey Office Connect JSON-API (HTTP POST)
• Authentifizierung: HTTP Basic Auth gegen MonKey Office, Firma-Auswahl via mbl-ident Header
• Abhängigkeiten: @modelcontextprotocol/sdk, express