Dataverse Local MCP

Подключите Claude (или любого MCP-клиента) к вашей среде Microsoft Dataverse / Dynamics 365 и работайте с данными на простом английском — запрашивайте записи, запускайте сохранённые представления, изучайте таблицы и столбцы, создавайте и обновляйте записи.

• Вход как обычно — ваша рабочая учётная запись Microsoft, в браузере, с тем же доверенным входом, что и в XrmToolBox. Работает из коробки: без регистрации приложения, без ключей API, без настройки администратора.

• Быстро со второго вызова — схема среды и сохранённые представления предварительно загружаются и кэшируются локально, поэтому вопросы о метаданных получают ответ мгновенно.

• Полный набор инструментов — OData-запросы, FetchXML (агрегаты и соединения), CRUD для сущностей и обнаружение метаданных — всё в одном сервере.

Руководства: Установка · Инструкция пользователя

Начало работы

1. Установите Node.js 18 или новее, если он ещё не установлен.

2. Установите сервер со страницы npm:

npm install -g dataverse-local-mcp

(Или пропустите установку и используйте npx -y dataverse-local-mcp как команду ниже.)

3. Добавьте его в MCP-клиент — для Claude Desktop добавьте это в claude_desktop_config.json, заменив URL на адрес вашей среды:

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

4. Войдите один раз. При первом запуске инструмента откроется браузер со входом в Microsoft — выберите рабочую учётную запись для этой среды. Токен сохраняется в ~/.dataverse-mcp/token-cache.json, поэтому повторный вход не потребуется, пока токен не истечёт. Если браузер вошёл не в ту учётную запись, всегда можно переключиться через выбор учётной записи.

Попробуйте: попросите MCP-клиента выполнить инструмент whoami — он должен вернуть ваш Dataverse UserId и OrganizationId. Затем попробуйте «покажи мои сохранённые представления» или «покажи топ-5 организаций по имени».

Related MCP server: Dataverse MCP Server

Инструменты

Данные

Схема

Примечания

Среда

Безопасная запись

Каждый изменяющий инструмент по умолчанию показывает предпросмотр. Без confirm: true он лишь описывает, что изменится — указывая целевую запись по её первичному имени — и ничего не вызывает. delete дополнительно показывает текущие значения полей, чтобы вы видели, что будет потеряно.

• По одной записи за раз. update и delete принимают id или фильтр where; если фильтру соответствует более одной записи, операция отклоняется и выводится список кандидатов, а не массовое изменение.

• Оптимистичная блокировка по умолчанию. Обновления и удаления передают ETag записи, поэтому запись, изменённая после вашего чтения, не будет перезаписана молча. Передайте concurrency: false, чтобы отказаться от проверки.

• Проверка перед отправкой. Неизвестные столбцы, столбцы, недопустимые для операции, значения вне диапазона набора параметров и неизвестные @odata.bind навигационные свойства отклоняются локально с сообщением, указывающим на проблему, — а не невнятной ошибкой платформы.

• Действия имеют последствия. Значительная часть работы в Dataverse выполняется через действия, а не прямые записи в таблицы, и их эффект шире, чем следует из вызова. Предпросмотр показывает сам вызов, но не его последствия: их невозможно узнать без выполнения.

Ошибки показывают hex-код Dataverse и сообщение, с распознанными формами (отказ в привилегиях, обнаружение дубликатов, отклонение бизнес-правилом или плагином, конфликт блокировки, неизвестный столбец), перед которыми добавляется строка на простом языке. Нераспознанные ошибки передаются как есть, без догадок.

Ресурсы

Полная схема OData $metadata (CSDL/EDMX) среды доступна как MCP-ресурс по адресу dataverse://metadata (application/xml, часто несколько мегабайт).

Как работает кэш

Сразу после handshake stdio сервер в фоновом режиме строит кэши. При запуске браузер не открывается: предварительная загрузка использует только тихую аутентификацию, поэтому при отсутствии кэшированного токена сервер ждёт и повторяет попытку после того, как ваш первый вызов инструмента завершит вход. Ничто не блокируется — холодный старт просто делает первый вызов медленнее.

Всё ключуется по OrganizationId, а не по URL среды, потому что URL меняются, а идентификаторы организаций — нет:

~/.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 и index.json всегда остаются локальными — они хранят настройки хранилища, поэтому не могут находиться внутри самого хранилища, которое описывают.

Область действия. Каждая таблица получает дешёвую сводку на уровне имён. Полные сведения о столбцах и связях кэшируются для всех настраиваемых таблиц плюс список разрешённых стандартных (по умолчанию Field Service и основные sales/service), с ограничением maxFullTables. Всё остальное подгружается лениво и объединяется при первом обращении инструмента.

Выборка строк по умолчанию отключена. Включите её для конкретной среды — и кэш также запишет для каждого столбца частоту заполнения и до пяти примеров значений не более чем из 20 строк — это самый полезный сигнал для таблиц с пустыми описаниями. Она читает реальные данные, поэтому остаётся строго добровольной и никогда не выбирает столбцы, чей тип или формат намекает на персональные данные, без явного разрешения.

Примечания

Описания в Dataverse часто пусты. Основной смысл несёт сама форма среды; остальное — человеческие знания, которые стоит накапливать, а не восстанавливать каждую сессию. Примечания хранятся в простом Markdown по пути environments/<organizationId>/annotations.md — доступны для ручного редактирования, отслеживаются в diff и безопасны для включения в репозиторий проекта.

## 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_

Каждое примечание несёт два независимых поля. Уверенность равна confirmed, только если утверждение сделано человеком; всё, что выяснила модель или инструмент, помечается inferred — именно поэтому примечания по умолчанию никогда не записываются обратно в описания Dataverse. Происхождение — human, preflight, velocity или model — определяет поведение перезаписи при повторном сканировании: автор может свободно заменить свою более раннюю заметку, человек заменяет что угодно, но ничто другое не перезаписывается. Если повторное сканирование противоречит заметке человека, сохраняются обе и помечаются для разрешения человеком, а не одна молча побеждает.

Заметки, созданные инструментами, оформляются как цитаты, чтобы вы сразу видели, что исходит от человека:

### rsm_scenariotype

> No plugins are registered on this column.

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

Обмен. export_annotations записывает файл куда угодно; import_annotations читает его обратно. В front matter указан organizationId, и импорт в другую организацию отклоняется, никогда не объединяется. Если обе стороны снабдили одну цель разными текстами, сохраняются оба и помечаются, а не один молча побеждает.

Дрейф. При кэшировании снимается отпечаток схемы. Когда он меняется, каждое примечание переходит в состояние valid, changed (тип или набор параметров изменились под заметкой) или orphaned (цель исчезла). Краткая сводка выводится в лог при подключении, конкретное предупреждение повторяется в describe_table, и ничего никогда не удаляется автоматически.

Режимы. Задаются явно для каждой среды, никогда не выводятся из привилегий — привилегии обычно шире намерений. consumer (по умолчанию) оставляет примечания локальными и никогда не пишет метаданные. maker дополнительно разрешает перенос подтверждённого примечания в само описание Dataverse.

Перенос документации в Dataverse

Если вы владеете схемой среды, подтверждённое примечание может стать настоящим описанием Dataverse. Это намеренно неудобно, и трение не следует уменьшать ради удобства: требуется режим maker, подтверждённое примечание (выводы отклоняются), отсутствие неразрешённого конфликта по нему, одна цель за вызов и явное подтверждение после чтения предпросмотра.

The written text is prefixed with a [dataverse-mcp] marker plus provenance and date. That marker is the point — without it a promoted note becomes indistinguishable from a human-authored description six months later, and something that read as a reasonable guess starts reading as fact.

Promotion is a metadata write: it creates an unmanaged customization in the active solution layer, which can mask later updates to a managed component, and publishing may be required before the description appears in the UI. The preview says all of this before you confirm, and the tool cannot undo it.

Where your documentation lives

By default everything sits under ~/.dataverse-mcp. Point it somewhere else with set_storage and both the annotations and the metadata cache follow — they always travel together, per environment.

The file-backed kinds are one implementation: an Obsidian vault, a OneDrive sync folder and a Basic Memory directory are all just folders, and git adds a commit step. Each environment gets its own subfolder (dataverse-mcp/<friendlyName>-<orgId prefix>) so a shared vault or repo can hold several without collision.

Notion needs an internal integration token in a NOTION_TOKEN environment variable — set it in your MCP client config, not in a file — and a notionPageId for the parent page, which must be shared with your integration. Each markdown line becomes one paragraph block, so the document round-trips exactly and stays readable and editable in Notion. Because Notion is a document store rather than a file store, the schema cache stays on local disk when Notion is selected; the annotations live in Notion.

Switching storage does not copy what you already have — run export_annotations first if you want to carry it across.

Upgrading from 0.3.x

list_entities and describe_entity are replaced by list_tables and describe_table, which read the new cache and fold in annotations and drift warnings. The 0.3.x cache directory ~/.dataverse-mcp/cache/<host>/ is no longer read and can be deleted; the new cache rebuilds itself on first connect. Your token cache is untouched, so no new sign-in is needed.

Build Spec (for contributors)

Goal

Build a standalone MCP server that talks directly to the Dataverse Web API. Going straight to the Web API keeps the server small and dependency-light, and lets it use the sign-in flow that works most broadly across machines and tenants — including tenants with strict Conditional Access policies. TypeScript, local Node host, no new app registration required.

Why this auth approach

This server uses the same proven auth pattern as XrmToolBox and Microsoft's own XRM Tooling samples: a Microsoft-provided, pre-consented public client with a loopback redirect, driven as a standard MSAL auth-code-plus-PKCE flow. It's the ordinary browser sign-in your tenant already trusts — it runs on every OS, satisfies Conditional Access policies that stop device-code flows, and needs no OS-level broker. Anywhere XrmToolBox connects, this connects.

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

This is a Microsoft multi-tenant sample app with user_impersonation delegated permission, no admin consent required. If XrmToolBox already connects successfully in your tenant, this same client ID is proven to already clear Conditional Access there.

Non-goals for v1

• No custom Entra app registration (use the well-known client ID above)

• No service principal / CI auth (interactive user auth only)

Repo layout

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

The assessment tools (powerpreflight, velocity) join as further packages/*, calling core directly as a library rather than going through the MCP server.

Dependencies

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

Runtime dependencies are @azure/msal-node, @modelcontextprotocol/sdk and open. HTTP calls use Node's built-in global fetch (hence the Node ≥ 18 requirement) — no HTTP client dependency.

Step 1 — Auth module (src/auth.ts)

Acquire and cache a token using acquireTokenInteractive, which spins up its own loopback listener, no manual HTTP server needed.

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

• Scope <environmentUrl>/.default

• Token cache persisted to ~/.dataverse-mcp/token-cache.json

• Silent acquisition from cache first, fall back to interactive (system browser opened via the open package; set DATAVERSE_MCP_NO_OPEN=1 to print the URL instead)

• Interactive sign-in always shows the account picker (prompt: select_account) so browser SSO can't silently hand back the wrong account's token

• Concurrent interactive sign-ins are deduped per environment — parallel requests share one browser window

• A silentOnly mode backs the cache prefetch: it throws instead of opening a browser, so background work never interrupts client startup

Step 2 — Dataverse Web API client (src/dataverseClient.ts)

Thin wrapper over the Dataverse Web API (/api/data/v9.2/) sending Authorization: Bearer, OData-MaxVersion: 4.0, OData-Version: 4.0 headers, retrying 429/503 on Retry-After so a bulk metadata build survives service protection limits. Covers whoAmI(), generic get(), record create/update/delete (PATCH sends If-Match: * so updates never silently upsert), FetchXML queries, saved views (savedquery + userquery, following @odata.nextLink), the raw $metadata EDMX, and metadata reads over EntityDefinitions.

Two Dataverse constraints shape the metadata calls: EntityDefinitions rejects $top and $orderby (it accepts $select and $filter), and DisplayName/Description/RequiredLevel come back as objects rather than scalars, so labels are extracted from UserLocalizedLabel.Label. Option sets need a cast — the client tries the EnumAttributeMetadata base cast (one call for picklist, state, status and multiselect) and falls back to the concrete casts where that isn't supported.

Step 3 — MCP server entry (src/server.ts)

Registers the tools listed in the Tools section above plus the dataverse://metadata resource, and kicks off the background cache prefetch after the transport connects. Uses the standard @modelcontextprotocol/sdk Server class with stdio transport, matching how @microsoft/dataverse mcp itself runs. The environment URL is passed as the first CLI argument.

Step 4 — First test

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

Expected: system browser opens once for interactive sign-in, token caches to ~/.dataverse-mcp/token-cache.json, subsequent runs reuse the cached token silently. Confirm success by calling the whoami tool and checking the returned UserId/BusinessUnitId. After the first sign-in, the background prefetch fills ~/.dataverse-mcp/cache/<org-host>/ with metadata.xml, entities.json, and saved-queries.json; later launches serve metadata and saved-view tools from that cache.

Step 5 — Claude Desktop config

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