business-central-mcp-server

Ein MCP-Server, der Dynamics 365 Business Central (online) Daten für einen MCP-Client (Claude Code, Claude Desktop, usw.) bereitstellt — Umgebungen, Unternehmen und jede Entität, die über die Standard-v2.0-API oder eine benutzerdefinierte AL-API erreichbar ist.

Er kommuniziert mit api.businesscentral.dynamics.com unter Verwendung eines Entra-Tokens für dieselbe Zielgruppe. Mit delegierter Authentifizierung (interaktiv / cli / azure-powershell) benötigt er keine App-Registrierung und keine Admin-Zustimmung — er agiert als angemeldeter Benutzer, eingeschränkt durch die Business-Central-Berechtigungssätze dieses Benutzers.

Tools

Lesen (immer aktiv)

Benutzerdefinierte APIs, die aus AL-Erweiterungen veröffentlicht werden, sind überall über api_route: "{publisher}/{group}/{version}" erreichbar.

Dokumente exportieren

Business Central stellt generierte Dokumente und hochgeladene Dateien als OData-Medienströme bereit, nicht als JSON-Felder. export_file ruft diese Bytes ab und schreibt sie auf die Festplatte; das Tool gibt den Pfad, die Größe und SHA-256 zurück, nicht den Inhalt, damit ein großes PDF nie in den Kontext des Modells gelangt. Es liest nur aus BC, aber da es in das lokale Dateisystem schreibt, registriert es sich in der Schreib-Stufe — setzen Sie BC_MCP_MODE=write, um es zu verwenden.

Prüfen Sie zuerst den Medienlink, dann laden Sie ihn herunter:

// get_entity — confirm the invoice has a renderable PDF
{ "entity_set": "salesInvoices", "record_id": "<guid>", "sub_path": "pdfDocument" }

// export_file — write the bytes out
{
  "entity_set": "salesInvoices",
  "record_id": "<guid>",
  "sub_path": "pdfDocument/pdfDocumentContent",
  "output_path": "./exports"
}

Nützliche Medienpfade: pdfDocument/pdfDocumentContent auf salesInvoices, salesCreditMemos und purchaseInvoices; content auf attachments; picture auf items und employees.

output_path kann eine Datei oder ein Verzeichnis sein — ein Verzeichnis (oder ein nachgestelltes Trennzeichen) bedeutet, dass der Dateiname aus dem Datensatz und dem erkannten Inhaltstyp abgeleitet wird. Lassen Sie es ganz weg, um auf BC_EXPORT_DIR und dann auf das Arbeitsverzeichnis zurückzufallen. Vorhandene Dateien werden nie überschrieben, es sei denn, Sie übergeben overwrite: true, und Downloads über max_bytes (standardmäßig 64 MiB) werden abgelehnt, bevor etwas geschrieben wird.

Schreiben (BC_MCP_MODE=write)

Jeder Schreibaufruf wird mit Zeitstempel, Tool, Ziel und Aufruferidentität in stderr protokolliert. Diese mutieren echte ERP-Daten — das Buchen eines Dokuments erzeugt Hauptbucheinträge, die nicht einfach gelöscht werden können. Richten Sie BC_DEFAULT_ENVIRONMENT während Experimenten auf eine Sandbox.

Destruktiv (BC_MCP_MODE=write und BC_MCP_ALLOW_DELETE=true)

Die destruktive Stufe ist standardmäßig deaktiviert. Wenn sie aktiviert ist, ist jeder Aufruf zuerst ein Plan: dry_run=true (Standard) gibt den Datensatz zurück, der entfernt würde, plus ein einmaliges confirm_token; nur ein zweiter Aufruf mit dry_run=false und diesem Token führt das Löschen aus, geschützt durch ein If-Match-Etag.

Related MCP server: Microsoft Business Central MCP Server

Installation in Claude Desktop

Laden Sie business-central-mcp-server-<version>.mcpb aus dem neuesten Release herunter und öffnen Sie es. Das ist die gesamte Installation — kein Klonen, kein npm install, kein Node auf Ihrem Rechner. Claude Desktop bringt seine eigene Node-Laufzeit mit und das Bundle enthält seine Abhängigkeiten.

Der Installationsdialog sammelt:

Bei der standardmäßigen interactive-Anmeldung lassen Sie Client-ID und Geheimnis leer. Der Server fällt auf den öffentlichen Azure-CLI-Client zurück, öffnet Ihren Browser und agiert als der angemeldete Benutzer unter den Business-Central-Berechtigungssätzen dieses Benutzers. Es gibt keine App-Registrierung und keine Admin-Zustimmung zu arrangieren.

Die Browseraufforderung erscheint bei jedem Neustart von Claude Desktop erneut. Tokens werden nur im Speicher gehalten; ihre Persistenz würde ein natives Anmeldeinformations-Cache-Modul und ein separates Bundle pro Plattform erfordern.

Das Bundle selbst erstellen

npm ci
npm run build:mcpb    # writes dist/business-central-mcp-server-<version>.mcpb
npm run verify:mcpb   # unpacks it and boots the server the way Desktop would

build:mcpb weigert sich, ein Bundle zu erzeugen, dessen Manifestversion nicht mit package.json übereinstimmt, oder dessen deklarierte Werkzeugliste nicht mit dem übereinstimmt, was der Server tatsächlich registriert.

Einrichtung (Claude Code und andere MCP-Clients)

cd business-central-mcp-server
npm install

Registrieren Sie es bei Ihrem MCP-Client. Beispiel .claude.json-Eintrag (delegierte Authentifizierung, schreibgeschützt):

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/business-central-mcp-server/index.js"],
      "env": {
        "AZURE_TENANT_ID": "<your-entra-tenant-id>",
        "BC_AUTH_MODE": "interactive",
        "BC_MCP_MODE": "read",
        "BC_DEFAULT_ENVIRONMENT": "Production"
      }
    }
  }
}

Um das Erstellen/Aktualisieren von Datensätzen und das Aufrufen gebundener Aktionen zu erlauben, setzen Sie "BC_MCP_MODE": "write". Um auch das Löschen zu erlauben, fügen Sie "BC_MCP_ALLOW_DELETE": "true" hinzu.

Setzen Sie BC_DEFAULT_COMPANY_ID auf einen Wert aus list_companies, wenn Sie in einem einzelnen Unternehmen arbeiten und company_id bei jedem Aufruf weglassen möchten.

Setzen Sie BC_EXPORT_DIR, um zu wählen, wohin export_file schreibt, wenn ein Aufruf output_path weglässt.

Siehe .env.example für die vollständige Liste der Umgebungsvariablen, einschließlich aller unterstützten Authentifizierungsmodi.

Authentifizierungshinweise

• Delegiert (empfohlen): interactive, device-code, cli oder azure-powershell. Keine App-Registrierung erforderlich; der Aufrufer agiert als angemeldeter Benutzer, eingeschränkt durch die BC-Berechtigungssätze und den Unternehmenszugriff dieses Benutzers.

• Dienstprinzipal: nicht interaktiv, aber der SP muss als Entra-Anwendung innerhalb von Business Central registriert sein (Seite „Entra-Anwendungen“, mit zugewiesenen Berechtigungssätzen), bevor die Datenebene ihn akzeptiert.

• list_environments verwendet die Admin-Center-Discovery-API, die zusätzlich BC-Admin-Center-Zugriff erfordert. Die anderen Tools funktionieren ohne sie, wenn Sie Umgebungsnamen direkt übergeben.

Anforderungen

• Eine Entra-Identität, die für Business Central im Zielmandanten lizenziert ist.

• Node.js >= 20, wenn Sie aus dem Quellcode ausführen. Das Claude-Desktop-Bundle hat keine solche Anforderung; Desktop stellt die Laufzeit bereit.

Lizenz

MIT — siehe LICENSE.