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 替换为你环境的 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。然后试试“列出我在 account 上保存的视图”或“按名称向我显示前 5 个 account”。

Related MCP server: Dataverse MCP Server

工具

数据

架构

批注

环境

安全写入

每个会变更数据的工具默认都会预览。在未传入 confirm: true 的情况下，它会精确描述将要发生什么变化——按主名称指出已解析的记录——并且不会调用任何内容。delete 还会列出记录当前的字段值，以便你看到即将丢失的内容。

• 一次只处理一条记录。 update 和 delete 接受一个 id 或 where 筛选器，任何匹配多条记录的情况都会被拒绝，并列出候选记录，而不是扩散处理。

• 默认启用乐观并发。 更新和删除会携带记录的 ETag，因此如果你读取记录后它又被更改，写入会失败，而不会静默覆盖他人的工作。传入 concurrency: false 可选择退出。

• 负载在发送前会经过检查。 未知列、对操作无效的列、超出范围的选项集值以及未知的 @odata.bind 导航属性都会在本地失败，并给出指明问题的消息——而不是不透明的平台 400 错误。

• 操作会级联。 Dataverse 中的许多实际工作是通过操作而非表写入完成的，其影响范围比调用本身所暗示的更广。预览显示的是调用，而不是其后果：这些后果在运行之前无法得知。

错误会显示 Dataverse 的十六进制代码和消息，并且对于可识别的情况（权限被拒绝、重复检测、业务规则或插件拒绝、并发、未知列），会加上一行通俗易懂的前缀。无法识别的内容会原样传递，而不会被猜测。

资源

环境的完整 OData $metadata（CSDL/EDMX）架构会作为 MCP 资源暴露在 dataverse://metadata（application/xml，通常有数 MB）。

缓存的工作原理

在 stdio 握手之后，服务器会立即在后台构建其缓存。它绝不会在启动时打开浏览器：预取仅使用静默身份验证，因此如果没有缓存的令牌，它会等待并在你的第一次工具调用登录后重试。没有任何操作会阻塞于此——冷启动仍然可用，只是第一次调用会稍慢。

所有内容都以 OrganizationId 为键，而不是环境 URL，因为 URL 会变而组织 id 不会：

~/.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 和核心销售/服务）都会缓存完整的列和关系详细信息，上限为 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 模式、一条已确认的批注（推断会被拒绝）、该批注上没有未解决的冲突、每次调用只处理一个目标，以及在阅读预览后给出明确的确认。

带 [dataverse-mcp] 标记以及来源和日期的书面文本就是重点——没有这个标记，一条笔记六个月后就会变得与人工撰写的描述无法区分，而原本读起来像合理猜测的内容就会开始被当作事实。

推广是一次元数据写入：它会在活动解决方案层创建一个非托管自定义项，这可能会掩盖托管组件后续的更新，而且在界面中显示描述之前可能还需要先发布。预览会在你确认之前就把这一切都展示出来，而该工具无法撤销此操作。

你的文档存放位置

默认情况下，所有内容都存放在 ~/.dataverse-mcp 下。使用 set_storage 可以将其指向其他位置，注解和元数据缓存会一起移动——它们始终同步，按环境分别存放。

基于文件的存储类型本质上是同一种实现：Obsidian 库、OneDrive 同步文件夹和 Basic Memory 目录都只是文件夹，而 git 只是多了一个提交步骤。每个环境都有自己的子文件夹（dataverse-mcp/<friendlyName>-<orgId prefix>），因此多个环境可以共用一个库或仓库而不会相互冲突。

Notion 需要在 NOTION_TOKEN 环境变量中提供内部集成令牌——请将其配置在 MCP 客户端配置中，而不是写在文件里——并且需要一个 notionPageId 作为父页面，该 ID 必须与你的集成共享。每条 Markdown 行会变成一个段落块，因此文档可以完整往返，并且在 Notion 中依然保持可读、可编辑。由于 Notion 是文档存储而非文件存储，模式缓存会保留在本地磁盘上（当选择 Notion 时）；注解则存放在 Notion 中。

切换存储方式不会自动复制已有内容——请先运行 export_annotations，如果你想把数据带过去的话。

从 0.3.x 升级

list_entities 和 describe_entity 已被 list_tables 和 describe_table 取代，后者会读取新的缓存，并整合注解和漂移警告。0.3.x 的缓存目录 ~/.dataverse-mcp/cache/<host>/ 不再被读取，可以删除；新缓存会在首次连接时自动重建。你的令牌缓存不受影响，因此无需重新登录。

构建规范（面向贡献者）

目标

构建一个独立的 MCP 服务器，直接与 Dataverse Web API 通信。直接对接 Web API 可以让服务器保持轻量、依赖少，并且能够使用在各类机器和租户上兼容性最好的登录流程——包括启用了严格条件访问策略的租户。使用 TypeScript，本地 Node 宿主，无需注册新的应用。

为什么采用这种认证方式

本服务器使用与 XrmToolBox 和微软自家的 XRM Tooling 示例相同的成熟认证模式：一个微软提供的、已预先授权的公共客户端，配合回环重定向，基于标准 MSAL 授权码 + PKCE 流程运行。就是你的租户已经信任的普通浏览器登录——它支持所有操作系统，能够满足会阻止设备代码流程的条件访问要求，而且不需要操作系统级的代理。XrmToolBox 能连接的地方，它都能连接。

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

这是一个微软的多租户示例应用，使用 user_impersonation 委派权限，无需管理员同意。如果 XrmToolBox 已经能在你的租户中成功连接，那么这个相同的客户端 ID 也已经被证明能够顺利通过那里的条件访问。

v1 的非目标

• 不提供自定义 Entra 应用注册（使用上述已知客户端 ID 即可）

• 不支持服务主体 / CI 认证（仅限交互式用户登录）

仓库结构

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

评估工具（powerpreflight、velocity）作为更多 packages/* 加入，直接以库的形式调用核心代码，而不是通过 MCP 服务器。

依赖项

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

运行时依赖为 @azure/msal-node、@modelcontextprotocol/sdk 和 open。HTTP 调用使用 Node 内置的全局 fetch（因此要求 Node ≥ 18）——不依赖任何 HTTP 客户端库。

第 1 步 — 认证模块（src/auth.ts）

使用 acquireTokenInteractive 获取并缓存令牌，该方法会自行启动一个回环监听器，无需手动搭建 HTTP 服务器。

• 客户端 ID 51f81489-12ee-4a9e-aaae-a2591f45987d，颁发机构 https://login.microsoftonline.com/common

• 作用域 <environmentUrl>/.default

• 令牌缓存持久化到 ~/.dataverse-mcp/token-cache.json

• 优先从缓存静默获取，失败时回退到交互式登录（通过 open 包打开系统浏览器；设置 DATAVERSE_MCP_NO_OPEN=1 则改为打印 URL）

• 交互式登录始终显示账户选择器（prompt: select_account），这样浏览器 SSO 就不会静默返回错误的账户令牌

• 并发的交互式登录按环境去重——并行请求共享同一个浏览器窗口

• silentOnly 模式用于缓存预取：它只抛错而不打开浏览器，因此后台任务永远不会打断用户操作

第 2 步 — Dataverse Web API 客户端（src/dataverseClient.ts）

对 Dataverse Web API（/api/data/v9.2/）的轻量封装，发送 Authorization: Bearer、OData-MaxVersion: 4.0、OData-Version: 4.0 请求头，在 429/503 时根据 Retry-After 重试，从而让批量元数据构建能够扛过服务保护限制。涵盖 whoAmI()、通用 get()、记录的创建/更新/删除（PATCH 会发送 If-Match: *，因此更新永远不会静默变成插入）、FetchXML 查询、已保存视图（savedview + userquery，并跟随 @odata.nextLink 分页）、原始 $metadata EDMX，以及基于 EntityDefinitions 的元数据读取。

Dataverse 的两个约束塑造了元数据调用的方式：EntityDefinitions 拒绝 $top 和 $orderby（但接受 $select 和 $filter），而且 DisplayName/Description/RequiredLevel 返回的是对象而非标量，因此需要从 UserLocalizedLabel.Label 中提取标签。选项集需要类型转换——客户端先尝试 EnumAttributeMetadata 基类转换（一次调用即可覆盖 picklist、state、status 和 multiselect），在不支持的情况下再回退到具体类型转换。

第 3 步 — MCP 服务器入口（src/server.ts）

注册上文工具章节列出的所有工具，以及 dataverse://metadata 资源，并在传输连接建立后在后台启动缓存预取。使用标准的 @modelcontextprotocol/sdk Server 类配合 stdio 传输，与 @microsoft/dataverse mcp 自身的运行方式一致。环境 URL 作为第一个命令行参数传入。

第 4 步 — 首次测试

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

预期结果：系统浏览器会打开一次以完成交互式登录，令牌缓存到 ~/.dataverse-mcp/token-cache.json，后续运行会静默复用缓存的令牌。通过调用 whoami 工具并检查返回的 UserId/BusinessUnitId 来确认成功。首次登录后，后台预取会在 ~/.dataverse-mcp/cache/<org-host>/ 下生成 metadata.xml、entities.json 和 saved-queries.json；之后的启动会从该缓存提供元数据和已保存视图工具。

第 5 步 — Claude Desktop 配置

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