Microsoft Business Central MCP Server

Model Context Protocol (MCP)-Server für Microsoft Dynamics 365 Business Central. Bietet KI-Assistenten direkten Zugriff auf Business-Central-Daten über korrekt formatierte API-v2.0-Aufrufe.

Funktionen

• ✅ Korrekte API-URLs: Verwendet das korrekte Format /companies(id)/resource (kein ODataV4-Segment)

• ✅ Keine Installation: Ausführung mit npx – keine Vorinstallation erforderlich

• ✅ Azure-CLI-Authentifizierung: Nutzt die vorhandene Azure-CLI-Anmeldung

• ✅ Client-Credentials-Authentifizierung: Service-to-Service-Authentifizierung für KI-Agenten

• ✅ Saubere Toolnamen: Keine Präfixe, nur get_schema, list_items usw.

• ✅ Vollständiges CRUD: Erstellen, Lesen, Aktualisieren und Löschen von Business-Central-Datensätzen

Installation

Mit npx (Empfohlen)

Keine Installation erforderlich! Konfiguration in Claude Desktop oder Claude Code:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0",
        "BC_COMPANY": "Your Company Name",
        "BC_AUTH_TYPE": "azure_cli"
      }
    }
  }
}

Hinweis für Windows: Verwenden Sie cmd mit /c wie oben gezeigt für eine ordnungsgemäße npx-Ausführung.

Mit Smithery

Installieren über Smithery:

npx -y @smithery/cli install @knowall-ai/mcp-business-central --client claude

Lokale Entwicklung

git clone https://github.com/knowall-ai/mcp-business-central.git
cd mcp-business-central
npm install
npm run build
node build/index.js

Konfiguration

Umgebungsvariablen

Konfigurationswerte ermitteln

1. Mandanten-ID: Finden Sie diese im Azure-Portal → Azure Active Directory → Übersicht

2. Umgebung: Normalerweise Production oder Sandbox

3. Unternehmensname: Der Anzeigename, der in Business Central angezeigt wird

Beispiel-URL-Format:

https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0

Authentifizierung

Empfehlung: Verwenden Sie die azure_cli-Authentifizierung – sie ist einfacher einzurichten und zuverlässiger. Die Methode client_credentials wird ebenfalls unterstützt, hat jedoch bekannte Konfigurationsherausforderungen bei der Einrichtung von Microsoft Entra Applications in Business Central. Details finden Sie in docs/TROUBLESHOOTING.adoc.

Option 1: Azure CLI (Empfohlen)

Die einfachste und zuverlässigste Authentifizierungsmethode. Verwendet Ihre vorhandene Azure-CLI-Anmeldung.

Voraussetzungen:

• Azure CLI installieren: https://docs.microsoft.com/cli/azure/install-azure-cli

• Anmelden: az login

• Zugriff überprüfen: az account get-access-token --resource https://api.businesscentral.dynamics.com

Konfiguration:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_AUTH_TYPE": "azure_cli",
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/Production/api/v2.0",
        "BC_COMPANY": "My Company"
      }
    }
  }
}

Option 2: Client Credentials (Service-to-Service)

Für automatisierte Systeme, die ohne Benutzerinteraktion ausgeführt werden müssen. Diese Methode verwendet den OAuth-2.0-Client-Credentials-Flow.

Hinweis: Diese Methode bringt bekannte Konfigurationsherausforderungen mit sich. Die Einrichtung von Microsoft Entra Applications in Business Central kann komplex sein, und die Erstellung des Anwendungsbenutzers funktioniert möglicherweise nicht wie erwartet. Ausführliche Hinweise finden Sie in docs/TROUBLESHOOTING.adoc.

Einrichtungsübersicht:

1. Azure-App-Registrierung erstellen:

   • Wechseln Sie zum Azure-Portal → Azure Active Directory → App-Registrierungen

   • Erstellen Sie eine neue Registrierung (einzelner Mandant)

   • Fügen Sie die API-Berechtigung hinzu: Dynamics 365 Business Central → app_access (Anwendungsberechtigung, NICHT delegierte)

   • Innenadministratorzustimmung für die Berechtigung erteilen

   • Fügen Sie eine Redirect-URI hinzu: https://businesscentral.dynamics.com/OAuthLanding.htm

2. Client-Geheimnis generieren:

   • Wechseln Sie in Ihrer App-Registrierung zu „Zertifikate und Geheimnisse“

   • Erstellen Sie ein neues client secret und speichern Sie es sicher

3. Business Central konfigurieren:

   • Suchen Sie in Business Central nach „Microsoft Entra Applications“

   • Klicken Sie auf + New und geben Sie die Client-ID Ihrer App ein

   • Legen Sie eine Beschreibung fest (diese wird zum Anwendungsbenutzername)

   • Setzen Sie den Status auf „Enabled“ – Sie sollten die Meldung „Ein Benutzer namens '[Description]' wird erstellt“ sehen

   • Fügen Sie Berechtigungssätze hinzu: D365 BUS FULL ACCESS (empfohlen) oder D365 READ

   • Lassen Sie das Feld Company leer, um Zugriff auf alle Unternehmen zu erhalten

   • Klicken Sie auf „Zustimmung erteilen“

4. Einrichtung überprüfen:

   • Der Anwendungsbenutzer sollte in der Benutzerliste in Business Central erschienen

   • Falls nicht, siehe docs/TROUBLESHOOTING.adoc für Lösungen

Referenzen:

• Wenn Sie Microsoft: Service-to-service authentication

• Business Central API Authentication

Verfügbare Tools

1. get_schema

Ruft OData-Metadaten für eine Business-Central-Ressource ab.

Parameter:

• resource (string, erforderlich): Ressourcenname (z. B. customers, contacts, salesOpportunities)

Beispiel:

{
  "resource": "customers"
}

2. list_items

Listet Elemente mit optionaler Filterung und Paginierung auf.

Parameter:

• resource (string, erforderlich): Ressourcenname

• filter (string, optional): OData-Filterausdruck

• top (number, optional): Maximale Anzahl der zurückzugebenden Elemente

• skip (number, optional): Anzahl der Elemente, die für die Paginierung übersprungen werden sollen

Beispiel:

{
  "resource": "customers",
  "filter": "displayName eq 'Contoso'",
  "top": 10
}

3. get_items_by_field

Ruft Elemente ab, die einem bestimmten Feldwert entsprechen.

Parameter:

• resource (string, erforderlich): Ressourcenname

• field (string, erforderlich): Name des Feldes, nach dem gefiltert werden soll

• value (string, erforderlich): Wert, der übereinstimmen soll

Beispiel:

{
  "resource": "contacts",
  "field": "companyName",
  "value": "Contoso Ltd"
}

4. create_item

Erstellt ein neues Element in Business Central.

Parameter:

• resource (string, erforderlich): Ressourcenname

• item_data (object, erforderlich): Daten des zu erstellenden Elements

Beispiel:

{
  "resource": "contacts",
  "item_data": {
    "displayName": "John Doe",
    "companyName": "Contoso Ltd",
    "email": "john.doe@contoso.com"
  }
}

5. update_item

Aktualisiert ein vorhandenes Element.

Parameter:

• resource (string, erforderlich): Ressourcenname

• item_id (string, erforderlich): Element-ID (GUID)

• item_data () (object, erforderlich): Zu aktualisierende Felder

Beispiel:

{
  "resource": "customers",
  "item_id": "1366066e-7688-f011-b9d1-6045bde9b95f",
  "item_data": {
    "displayName": "Updated Name"
  }
}

6. delete_item

Löscht ein Element aus Business Central.

Parameter:

• resource (string, erforderlich): Ressourcenname

• item_id (string, erforderlich): Element-ID (GUID)

Beispiel:

{
  "resource": "contacts",
  "item_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

Häufige Ressourcen

• companies – Unternehmensinformationen

• customers – Kundendatensätze

• contacts – Kontaktdatensätze

• salesOpportunities – Verkaufschancen

• salesQuotes – Verkaufsangebote

• salesOrders – Verkaufsbestellungen

• salesInvoices – Verkaufsrechnungen

• items – Produkt-/Dienstleistungsartikel

• vendors – Lieferantendatensätze

Fehlerbehebung

Detaillierte Fehlerbehebungsleitfäden finden Sie in docs/TROUBLESHOOTING.adoc. Diese behandeln:

• Authentifizierungsprobleme (401-Fehler, Token-Probleme)

• Herausforderungen bei der Einrichtung von client_credentials und bekannte Probleme

• Fehler „Unternehmen nicht gefunden“

• Umgebungsspezifische Konfiguration (Production und Sandbox)

Entwicklung

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Lizenz

MIT

Mitwirken

Issues und Pull Requests sind willkommen unter https://github.com/knowall-ai/mcp-business-central.

Verwandte Projekte

• MCP Specification: modelcontextprotocol.io