Dataverse Local MCP

Verbinden Sie Claude (oder einen beliebigen MCP-Client) mit Ihrer Microsoft Dataverse / Dynamics 365-Umgebung und arbeiten Sie mit Ihren Daten in einfacher Sprache – Datensätze abfragen, gespeicherte Ansichten ausführen, Tabellen und Spalten erkunden, Zeilen erstellen und aktualisieren.

• Melden Sie sich wie gewohnt an – mit Ihrem eigenen Microsoft-Geschäftskonto, im Browser, mit derselben vertrauenswürdigen Anmeldung, die auch XrmToolBox verwendet. Funktioniert sofort: keine App-Registrierung, keine API-Schlüssel, keine Admin-Einrichtung.

• Schnell ab dem zweiten Aufruf – das Schema Ihrer Umgebung und gespeicherte Ansichten werden vorab geladen und lokal zwischengespeichert, sodass Metadatenfragen sofort beantwortet werden.

• Vollständige Werkzeugkiste – OData-Abfragen, FetchXML (Aggregationen und Joins), Entitäts-CRUD und Metadaten-Erkennung in einem Server.

Anleitungen: Einrichtung · Benutzerhandbuch

Erste Schritte

1. Installieren Sie Node.js 18 oder neuer, falls Sie es nicht haben.

2. Installieren Sie den Server über die npm-Installationsseite:

npm install -g dataverse-local-mcp

(Oder überspringen Sie die Installation und verwenden Sie npx -y dataverse-local-mcp als Befehl unten.)

3. Fügen Sie es Ihrem MCP-Client hinzu – für Claude Desktop fügen Sie dies zu claude_desktop_config.json hinzu und ersetzen Sie die URL durch die Ihrer Umgebung:

{
  "mcpServers": {
    "dataverse": {
      "command": "dataverse-local-mcp",
      "args": ["https://yourorg.crm.dynamics.com"]
    }
  }
}

4. Einmal anmelden. Wenn zum ersten Mal ein Tool ausgeführt wird, öffnet Ihr Browser eine Microsoft-Anmeldung – wählen Sie Ihr Geschäftskonto für diese Umgebung. Das Token wird unter ~/.dataverse-mcp/token-cache.json zwischengespeichert, sodass Sie erst wieder gefragt werden, wenn es abläuft. Falls der Browser Sie mit dem falschen Konto anmeldet, wird immer eine Kontenauswahl angezeigt, sodass Sie wechseln können.

Probieren Sie es aus: Bitten Sie Ihren MCP-Client, das Tool whoami auszuführen – es sollte Ihre Dataverse-UserId und OrganizationId zurückgeben. Versuchen Sie dann „liste meine gespeicherten Ansichten zu Konten“ oder „zeig mir die Top-5-Konten nach Name“.

Related MCP server: Dataverse MCP Server

Tools

Daten

Schema

Anmerkungen

Umgebung

Sicheres Schreiben

Jedes verändernde Tool zeigt standardmäßig eine Vorschau. Ohne confirm: true aufgerufen, beschreibt es genau, was sich ändern würde – benennt den aufgelösten Datensatz mit seinem primären Namen – und ruft nichts auf. delete listet zusätzlich die aktuellen Feldwerte des Datensatzes auf, sodass Sie sehen, was gleich verloren geht.

• Immer nur ein Datensatz. update und delete akzeptieren eine ID oder einen where-Filter, und alles, was mehr als einen Datensatz trifft, wird abgelehnt, wobei die Kandidaten aufgelistet werden, statt aufzufächern.

• Standardmäßig optimistische Nebenläufigkeit. Updates und Löschungen tragen das ETag des Datensatzes, sodass ein Schreibvorgang auf einen Datensatz, der sich nach dem Lesen geändert hat, fehlschlägt, statt stillschweigend die Arbeit eines anderen zu überschreiben. Übergeben Sie concurrency: false, um dies zu deaktivieren.

• Payloads werden geprüft, bevor sie gesendet werden. Unbekannte Spalten, für die Operation ungültige Spalten, Optionssatzwerte außerhalb des gültigen Bereichs und unbekannte @odata.bind-Navigationseigenschaften schlagen alle lokal mit einer Meldung fehl, die das Problem benennt – nicht mit einem undurchsichtigen Plattform-400.

• Aktionen haben Folgewirkungen. Ein Großteil der eigentlichen Arbeit in Dataverse geschieht über Aktionen und nicht über Tabellenschreibvorgänge, und ihre Auswirkungen reichen weiter, als der Aufruf vermuten lässt. Die Vorschau zeigt den Aufruf, nicht seine Konsequenzen: Diese sind ohne Ausführung nicht bekannt.

Fehler zeigen den Dataverse-Hexcode und die Meldung; bekannte Formen (fehlende Berechtigung, Duplikaterkennung, Ablehnung durch Geschäftsregel oder Plugin, Nebenläufigkeit, unbekannte Spalte) erhalten eine vorangestellte Zeile in verständlicher Sprache. Alles Unbekannte wird unverändert durchgereicht, statt geraten zu werden.

Ressourcen

Das vollständige OData-$metadata-Schema (CSDL/EDMX) der Umgebung wird als MCP-Ressource unter dataverse://metadata bereitgestellt (application/xml, oft mehrere MB).

So funktioniert der Cache

Direkt nach dem Stdio-Handshake baut der Server seine Caches im Hintergrund auf. Er öffnet beim Start nie einen Browser: Der Vorabruf verwendet nur die stille Authentifizierung. Ohne zwischengespeichertes Token wartet er also und versucht es erneut, nachdem sich Ihr erster Tool-Aufruf angemeldet hat. Nichts blockiert darauf – ein Kaltstart funktioniert trotzdem, nur langsamer beim ersten Aufruf.

Alles wird über die OrganizationId identifiziert, nicht über die Umgebungs-URL, denn URLs ändern sich, Organisations-IDs nicht:

~/.dataverse-mcp/
  token-cache.json
  environments/
    index.json                 # host -> organizationId, so a warm start needs no network
    <organizationId>/
      config.json              # url, friendly name, mode, storage, scope, sampling
      schema.json              # cached metadata          } these two follow
      schema.fingerprint       # hash for drift detection } your storage choice
      annotations.md           # your documentation       }
      metadata.xml             # the $metadata resource   } always local:
      saved-queries.json       #                          } large, derived, cheap to refetch

config.json und index.json bleiben immer lokal – sie enthalten die Speichereinstellungen selbst und können daher nicht in dem Backend liegen, das sie beschreiben.

Umfang. Jede Tabelle erhält eine kostengünstige Zusammenfassung auf Namensebene. Vollständige Spalten- und Beziehungsdetails werden für alle benutzerdefinierten Tabellen sowie eine Allowlist von Standardtabellen (standardmäßig Field Service und Kernvertrieb/-service) zwischengespeichert, begrenzt durch maxFullTables. Alles andere wird verzögert abgerufen und beim ersten Zugriff eines Tools zusammengeführt.

Zeilen-Sampling ist standardmäßig deaktiviert. Aktivieren Sie es pro Umgebung, und der Cache zeichnet zusätzlich pro Spalte die Füllrate und bis zu fünf Beispielwerte aus höchstens 20 Zeilen auf – das mit Abstand nützlichste Signal für Tabellen mit leeren Beschreibungen. Es liest echte Daten, bleibt daher eine Opt-in-Funktion, und es sampelt niemals Spalten, deren Typ oder Format auf personenbezogene Daten hindeutet, es sei denn, Sie erlauben es ausdrücklich.

Anmerkungen

Dataverse-Beschreibungen sind häufig leer. Die eigene Struktur der Umgebung trägt den Großteil der Bedeutung; der Rest ist menschliches Wissen, das es wert ist, angesammelt zu werden, statt es in jeder Sitzung neu abzuleiten. Anmerkungen liegen in einfachem Markdown unter environments/<organizationId>/annotations.md – von Menschen bearbeitbar, diffbar und bedenkenlos in ein Engagement-Repository eincheckbar.

## rsm_cipscenariocandidate

Candidate records for capital improvement plan scenario modelling. Populated by
the scenario engine, not by users directly.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: human_

### rsm_scenariotype

Picklist. 1 = replacement, 2 = rehabilitation, 3 = deferral.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: inferred_ · _provenance: human_

Jede Anmerkung trägt zwei unabhängige Felder. Konfidenz ist nur dann confirmed, wenn ein Mensch sie angegeben hat; alles, was ein Modell oder Tool herausgefunden hat, ist inferred – genau deshalb werden Anmerkungen standardmäßig nie in Dataverse-Beschreibungen zurückgeschrieben. Herkunft ist human, preflight, velocity oder model und bestimmt das Überschreibverhalten beim erneuten Scannen: Ein Autor kann seine eigene frühere Notiz frei ersetzen, und ein Mensch kann alles ersetzen, aber nichts anderes überschreibt. Wenn ein erneuter Scan einer Notiz einer Person widerspricht, werden beide behalten und zur Klärung durch einen Menschen markiert, statt dass eine stillschweigend gewinnt.

Von Tools erstellte Notizen werden als Blockzitate dargestellt, damit Sie auf einen Blick erkennen, was von einer Person stammt:

### rsm_scenariotype

> No plugins are registered on this column.

_author: preflight_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: preflight_

Teilen. export_annotations schreibt die Datei überall hin, wo Sie möchten; import_annotations liest eine zurück. Die Front Matter enthält die organizationId, und ein Import in eine andere Organisation wird abgelehnt, niemals zusammengeführt. Wenn beide Seiten dasselbe Ziel mit unterschiedlichem Text annotieren, werden beide behalten und markiert, statt dass eine stillschweigend gewinnt.

Drift. Beim Cache-Aufbau wird ein Fingerabdruck über das Schema erfasst. Wenn er sich ändert, wird jede Anmerkung zu valid, changed (der Typ oder Optionssatz hat sich unter der Notiz verschoben) oder orphaned (das Ziel ist verschwunden) aufgelöst. Beim Verbinden wird eine kurze Zusammenfassung protokolliert, die spezifische Warnung wiederholt sich inline in describe_table, und es wird nie automatisch etwas gelöscht.

Modi. Pro Umgebung explizit festgelegt, niemals aus Berechtigungen abgeleitet – Berechtigungen sind in der Regel weiter gefasst als die Absicht. consumer (Standard) hält Anmerkungen lokal und schreibt niemals Metadaten. maker erlaubt zusätzlich, eine bestätigte Anmerkung in die Dataverse-Beschreibung selbst zu übernehmen.

Dokumentation in Dataverse übernehmen

Wenn Sie das Schema einer Umgebung besitzen, kann eine bestätigte Anmerkung zur echten Dataverse-Beschreibung werden. Das ist bewusst umständlich, und die Hürde sollte nicht aus Bequemlichkeit gesenkt werden: Es erfordert den maker-Modus, eine bestätigte Anmerkung (Rückschlüsse werden abgelehnt), keinen ungelösten Konflikt dazu, ein Ziel pro Aufruf und eine ausdrückliche Bestätigung nach dem Lesen der Vorschau.

Der geschriebene Text ist mit einem [dataverse-mcp]-Marker plus Herkunft und Datum versehen. Dieser Marker ist der entscheidende Punkt — ohne ihn wird aus einer geförderten Notiz sechs Monate später eine nicht mehr von einer menschlich verfassten Beschreibung unterscheidbare Notiz, und etwas, das wie eine vernünftige Vermutung wirkte, liest sich plötzlich als Tatsache.

Förderung ist ein Metadaten-Schreibvorgang: Sie erstellt eine nicht verwaltete Anpassung in der aktiven Solution-Ebene, die spätere Updates einer verwalteten Komponente überdecken kann, und eine Veröffentlichung kann erforderlich sein, bevor die Beschreibung in der Benutzeroberfläche erscheint. Die Vorschau sagt all das, bevor du bestätigst, und das Tool kann es nicht rückgängig machen.

Wo deine Dokumentation lebt

Standardmäßig liegt alles unter ~/.dataverse-mcp. Verweise mit set_storage auf einen anderen Ort, und sowohl die Annotationen als auch der Metadaten-Cache folgen — sie reisen immer zusammen, pro Umgebung.

Die dateibasierten Arten sind eine Implementierung: Ein Obsidian-Vault, ein OneDrive-Synchronisierungsordner und ein Basic Memory-Verzeichnis sind alle nur Ordner, und git fügt einen Commit-Schritt hinzu. Jede Umgebung erhält ihren eigenen Unterordner (dataverse-mcp/<friendlyName>-<orgId prefix>), sodass ein gemeinsamer Vault oder ein gemeinsames Repo mehrere ohne Kollision aufnehmen kann.

Notion benötigt ein internes Integrations-Token in einer NOTION_TOKEN-Umgebungsvariable — setze es in deiner MCP-Client-Konfiguration, nicht in einer Datei — und eine notionPageId für die übergeordnete Seite, die mit deiner Integration geteilt sein muss. Jede Markdown-Zeile wird zu einem Absatzblock, sodass das Dokument exakt hin- und herreist und in Notion lesbar und bearbeitbar bleibt. Da Notion eher ein Dokument- als ein Dateispeicher ist, bleibt der Schema-Cache bei Auswahl von Notion auf der lokalen Festplatte; die Annotationen leben in Notion.

Das Wechseln des Speichers kopiert nicht, was du bereits hast — führe zuerst export_annotations aus, wenn du es übertragen möchtest.

Upgrade von 0.3.x

list_entities und describe_entity werden durch list_tables und describe_table ersetzt, die den neuen Cache lesen und Annotationen sowie Drift-Warnungen einbeziehen. Das 0.3.x-Cache-Verzeichnis ~/.dataverse-mcp/cache/<host>/ wird nicht mehr gelesen und kann gelöscht werden; der neue Cache baut sich bei der ersten Verbindung selbst neu auf. Dein Token-Cache bleibt unberührt, sodass keine erneute Anmeldung erforderlich ist.

Build-Spezifikation (für Mitwirkende)

Ziel

Einen eigenständigen MCP-Server bauen, der direkt mit der Dataverse-Web-API spricht. Der direkte Weg über die Web-API hält den Server klein und abhängigkeitsarm und ermöglicht die Verwendung des Anmeldeablaufs, der am breitesten über Maschinen und Mandanten hinweg funktioniert — einschließlich Mandanten mit strengen Conditional-Access-Richtlinien. TypeScript, lokaler Node-Host, keine neue App-Registrierung erforderlich.

Warum dieser Auth-Ansatz

Dieser Server verwendet dasselbe bewährte Auth-Muster wie XrmToolBox und Microsofts eigene XRM-Tooling-Beispiele: einen von Microsoft bereitgestellten, vorab zugestimmten öffentlichen Client mit Loopback-Redirect, gesteuert als standardmäßiger MSAL-Auth-Code-plus-PKCE-Ablauf. Es ist die gewöhnliche Browser-Anmeldung, der dein Mandant bereits vertraut — sie läuft auf jedem Betriebssystem, erfüllt Conditional-Access-Richtlinien, die Device-Code-Abläufe stoppen, und benötigt keinen Broker auf Betriebssystemebene. Überall, wo XrmToolBox sich verbindet, verbindet sich dieses.

Client ID: 51f81489-12ee-4a9e-aaae-a2591f45987d
Redirect URI: http://localhost
Authority: https://login.microsoftonline.com/common
Scope: <environmentUrl>/.default

Dies ist eine Microsoft-Multi-Tenant-Beispiel-App mit delegierter user_impersonation-Berechtigung, keine Admin-Zustimmung erforderlich. Wenn XrmToolBox in deinem Mandanten bereits erfolgreich eine Verbindung herstellt, ist nachgewiesen, dass dieselbe Client-ID dort bereits Conditional Access passiert.

Nicht-Ziele für v1

• Keine benutzerdefinierte Entra-App-Registrierung (verwende die bekannte Client-ID oben)

• Kein Dienstprinzipal / CI-Auth (nur interaktive Benutzer-Auth)

Repo-Struktur

packages/
  core/                    @dataverse-platform/core — shared library, private
    src/
      index.ts             public surface
      auth.ts              MSAL interactive + silent acquisition
      cache.ts             atomic read/write helpers
      paths.ts             ~/.dataverse-mcp layout
      environment.ts       per-environment config, OrganizationId resolution
      dataverseClient.ts   Web API calls
      writes.ts            preview/confirm, validation, single-record resolution
      promotion.ts         annotation -> Dataverse description, maker mode only
      errors.ts            Dataverse error translation
      store.ts             $metadata + saved-view warm cache
      metadata/            schema cache: types, fingerprint, build, sampling
      annotations/         markdown model, store, drift detection
      storage/             backends: directory/git presets, Notion
  mcp-server/              dataverse-local-mcp — published to npm
    src/
      server.ts            MCP wiring
      tools/               tool definitions and formatters
    build.mjs              esbuild bundle (inlines core)
    prepack.mjs            stages README/LICENSE for packing
package.json               npm workspaces root
tsconfig.base.json

Die Bewertungstools (powerpreflight, velocity) kommen als weitere packages/* hinzu und rufen Core direkt als Bibliothek auf, statt über den MCP-Server zu gehen.

Abhängigkeiten

npm install          # installs every workspace
npm run typecheck    # tsc -b across packages
npm run build        # core via tsc, mcp-server bundled via esbuild
npm run clean        # removes dist and tsbuildinfo

Laufzeitabhängigkeiten sind @azure/msal-node, @modelcontextprotocol/sdk und open. HTTP-Aufrufe verwenden den eingebauten globalen fetch von Node (daher die Node-≥-18-Anforderung) — keine HTTP-Client-Abhängigkeit.

Schritt 1 — Auth-Modul (src/auth.ts)

Ein Token mit acquireTokenInteractive abrufen und cachen, das einen eigenen Loopback-Listener startet, kein manueller HTTP-Server erforderlich.

• Client-ID 51f81489-12ee-4a9e-aaae-a2591f45987d, Authority https://login.microsoftonline.com/common

• Bereich <environmentUrl>/.default

• Token-Cache persistiert in ~/.dataverse-mcp/token-cache.json

• Stiller Abruf aus dem Cache zuerst, Rückfall auf interaktiv (Systembrowser über das open-Paket geöffnet; setze DATAVERSE_MCP_NO_OPEN=1, um stattdessen die URL auszugeben)

• Die interaktive Anmeldung zeigt immer die Kontenauswahl (prompt: select_account), sodass Browser-SSO nicht stillschweigend das Token des falschen Kontos zurückgeben kann

• Gleichzeitige interaktive Anmeldungen werden pro Umgebung dedupliziert — parallele Anfragen teilen sich ein Browserfenster

• Ein silentOnly-Modus unterstützt den Cache-Prefetch: Er wirft einen Fehler, statt einen Browser zu öffnen, sodass Hintergrundarbeit den Client-Start nie unterbricht

Schritt 2 — Dataverse-Web-API-Client (src/dataverseClient.ts)

Dünner Wrapper um die Dataverse-Web-API (/api/data/v9.2/), der Authorization: Bearer, OData-MaxVersion: 4.0, OData-Version: 4.0-Header sendet und 429/503 auf Retry-After erneut versucht, sodass ein Massen-Metadatenaufbau Service-Protection-Limits übersteht. Abgedeckt sind whoAmI(), generisches get(), Datensatz-Erstellen/-Aktualisieren/-Löschen (PATCH sendet If-Match: *, sodass Updates nie stillschweigend Upserts werden), FetchXML-Abfragen, gespeicherte Ansichten (savedquery + userquery, mit Verfolgung von @odata.nextLink), das rohe $metadata-EDMX und Metadaten-Lesevorgänge über EntityDefinitions.

Zwei Dataverse-Einschränkungen prägen die Metadatenaufrufe: EntityDefinitions lehnt $top und $orderby ab (es akzeptiert $select und $filter), und DisplayName/Description/RequiredLevel kommen als Objekte statt als Skalare zurück, sodass Beschriftungen aus UserLocalizedLabel.Label extrahiert werden. Optionsets benötigen einen Cast — der Client versucht den EnumAttributeMetadata-Basiscast (ein Aufruf für Picklist, State, Status und Multiselect) und fällt auf die konkreten Casts zurück, wo das nicht unterstützt wird.

Schritt 3 — MCP-Server-Einstieg (src/server.ts)

Registriert die im Abschnitt „Tools" oben aufgeführten Tools plus die dataverse://metadata-Ressource und startet den Hintergrund-Cache-Prefetch, nachdem der Transport verbunden ist. Verwendet die standardmäßige Server-Klasse des @modelcontextprotocol/sdk mit Stdio-Transport, passend dazu, wie @microsoft/dataverse mcp selbst läuft. Die Umgebungs-URL wird als erstes CLI-Argument übergeben.

Schritt 4 — Erster Test

npm run build
node dist/server.js https://yourorg.crm.dynamics.com

Erwartet: Der Systembrowser öffnet sich einmal für die interaktive Anmeldung, das Token wird in ~/.dataverse-mcp/token-cache.json gecacht, nachfolgende Läufe verwenden das gecachte Token still wieder. Bestätige den Erfolg, indem du das whoami-Tool aufrufst und die zurückgegebene UserId/BusinessUnitId prüfst. Nach der ersten Anmeldung füllt der Hintergrund-Prefetch ~/.dataverse-mcp/cache/<org-host>/ mit metadata.xml, entities.json und saved-queries.json; spätere Starts bedienen Metadaten- und gespeicherte-Ansichten-Tools aus diesem Cache.

Schritt 5 — Claude-Desktop-Konfiguration

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/full/path/to/DataVerseLocalMCP/dist/server.js", "https://yourorg.crm.dynamics.com"]
    }
  }
}