使用 Dataverse CLI 处理数据（预览版）

注释

  • 这是一项预览功能。
  • 预览功能不适合生产使用且功能可能受限。 这些功能在正式发布之前可供使用，以便客户可以抢先体验并提供反馈。

Dataverse CLI 是用于Microsoft Dataverse的跨平台命令行工具。 使用它来管理身份验证配置文件、查询和修改数据、发现和调用 API、处理链接的财务和运营（ERP）环境，并运行模型上下文协议（MCP）服务器，让 AI 助手与环境交互。

CLI 作为 @microsoft/dataverse npm 包分发。 关键功能包括：

  • 与 Microsoft Power Platform CLI 身份验证配置文件兼容的基于配置文件的身份验证。
  • 用于查看当前组织和列出可访问环境的环境命令（org / env）。
  • 用于查询、获取、创建、更新、更新、更新插入、删除和计数记录的数据命令;将文件上传到文件列;并关联或取消关联相关记录。
  • 用于发现、描述和调用 Dataverse 自定义 API 和 ERP 可调用服务终结点的动态 api 命令，或发送原始经过身份验证的 HTTP 请求。
  • skill 用于上传、下载、列出和删除 AI 代理使用的 Dataverse 技能的命令。
  • 适用于 AI 客户端（如 Claude Desktop）的 MCP 服务器。
  • --json 输出用于脚本编写的受支持命令。

有关命令及其参数的完整列表，请参阅 Dataverse CLI 参考。

先决条件

若要安装和运行 CLI，需要在受支持的平台上安装 Node.js （包括 npm）。

在可以使用 MCP 服务器对 Dataverse 环境进行身份验证并连接到 Dataverse 环境之前，管理员必须完成以下三个设置步骤：

  1. 授予管理员同意（Azure 租户管理员）。 Azure 租户管理员通过访问 https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457、登录后接受所请求的权限，为 Dataverse MCP CLI 工具应用程序授予管理员同意授权。 将 {your-tenant-id} 替换为你的实际 Azure 租户 ID。

  2. 启用 MCP 服务器（Dataverse 管理员）。 Dataverse 组织管理员为环境启用 MCP 服务器功能。 请参阅“启用 Dataverse MCP”（生产）或“启用 Dataverse MCP”（预览版）。

  3. 允许使用 MCP CLI 工具（Dataverse 管理员）。 Dataverse 组织管理员将 Dataverse MCP CLI 工具添加到允许的客户端应用程序列表中，方法是遵循 “配置 MCP 客户端列表 ”并使用应用 ID 0c412cc3-0dd6-449b-987f-05b053db9457添加应用程序。 它在 UI 中显示为 Dataverse MCP CLI 工具 。

    或者，具有 Dataverse 管理员权限的用户可以使用命令添加应用程序mcp allow。

注释

必须先完成所有三个步骤，然后才能通过 MCP 服务器成功进行身份验证并连接到 Dataverse 环境。

支持的平台

Dataverse CLI 支持以下平台：

  • Windows （x64， Arm64）
  • macOS （x64， Arm64 / Apple silicon）
  • Linux （x64，Arm64）

安装 Dataverse CLI

使用 npm 全局安装 CLI：

npm install -g @microsoft/dataverse

或者，使用 npx 无需安装即可运行 CLI：

npx @microsoft/dataverse <command> [options]

若要安装特定版本或更新到最新版本，请使用 install 以下命令：

dataverse install latest
dataverse install 1.0.0

运行命令时，CLI 会自动检查 npm 是否有较新版本。 如果较新版本可用，它会通知你，以便你可以更新。

与 Claude Desktop 配合使用

可以将 CLI 作为 MCP 服务器运行，以便 Claude Desktop 可以与 Dataverse 环境交互。

添加它的最快捷方法是使用 Claude CLI：

claude mcp add dataverse -t stdio -- npx -y @microsoft/dataverse mcp https://yourorg.crm.dynamics.com

若要手动配置 Claude Desktop，请编辑 MCP 配置文件：

  • Windows： %APPDATA%\Claude\claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json

将服务器添加到 mcpServers 节：

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@microsoft/dataverse", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}

若要捕获详细的诊断信息，请将 --log-level Debug 和 --log-file 选项添加到 args 数组中。 若要使用预览版 MCP 终结点，请添加 --preview 选项。 更改配置后重启 Claude Desktop。

有关启动服务器的详细信息，请参阅 mcp 命令。

Authentication

CLI 使用 Microsoft 身份验证库 （MSAL） 进行身份验证。 它会在本地缓存身份验证配置文件和令牌。 这些配置文件可与 Microsoft Power Platform CLI 身份验证配置文件配合使用。

首次连接时，使用 auth create 命令 创建配置文件：

dataverse auth create --environment https://myorg.crm.dynamics.com

此命令将打开浏览器或系统身份验证对话框。 登录后，个人资料会被保存。 后续命令（包括 mcp）使用缓存的令牌，而无需再次提示你。

若要使用多个环境，请为每个环境创建一个命名配置文件。 使用 auth select 以下命令在它们之间切换：

dataverse auth create --environment https://dev.crm.dynamics.com --name dev
dataverse auth create --environment https://prod.crm.dynamics.com --name prod
dataverse auth select --name dev

对于 CI/CD 等无人值守场景，请使用服务主体进行身份验证：

dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId> --environment https://myorg.crm.dynamics.com

对于没有浏览器的环境，请通过添加 --deviceCode 选项来使用设备代码流。 若要查看所有身份验证选项，包括证书、托管标识和联合身份验证，请运行 dataverse auth create --help。 若要查看、列出和删除配置文件，请参阅auth who和auth listauth remove命令。

获取帮助

每个命令和子命令都支持该 --help 选项。 其中列出了使用情况、选项和示例。 例如：

dataverse --help
dataverse auth --help
dataverse auth create --help
dataverse org --help
dataverse mcp --help
dataverse data query --help

支持的 MCP 操作

MCP 服务器支持以下操作：

  • 工具：列出和调用 Dataverse 工具。
  • 提示：列出和检索提示。
  • 资源：列出和读取 Dataverse 资源。

当环境 URL 是财务和运营 (ERP) 主机时，例如 https://myorg.operations.dynamics.com，mcp 命令会自动路由到 ERP MCP 服务器。

Troubleshooting

验证设置

在启动服务器之前，请使用 --validate 以下选项验证身份验证和 MCP 配置：

dataverse mcp https://yourorg.crm.dynamics.com --validate

此选项检查 GA 和预览终结点，并验证身份验证是否正常工作，已启用 MCP 服务器，并且 MCP CLI 工具位于允许的应用程序列表中。 如果验证失败，输出将标识要完成的先决条件步骤。

启用日志记录

如果遇到问题，请启用文件日志记录以捕获详细的诊断信息：

dataverse mcp https://yourorg.crm.dynamics.com --log-level Debug --log-file

日志文件将写入系统的临时目录。 开始记录日志时会显示确切的位置。

常见问题

找不到适用于平台的兼容二进制文件

CLI 支持Windows（x64、Arm64）、macOS（x64、Arm64）和 Linux（x64、Arm64）。 预生成的二进制文件不支持其他平台。

身份验证失败

  • 确认你有权访问 Dataverse 环境。
  • 确认环境 URL 正确。
  • 使用 auth create 命令清除令牌缓存并重新进行身份验证。

Claude Desktop 中的 MCP 连接问题

  • 验证配置 JSON 语法是否正确。
  • 验证环境 URL 是否可访问。
  • 添加 --log-file 选项以捕获详细的错误消息。
  • 更改配置后重启 Claude Desktop。

另见

Dataverse CLI 参考

  • Last updated on