Power BI Modeling MCP

目的

安装、配置和使用 Microsoft 官方 Power BI Modeling MCP Server，使 WorkBuddy 能连接 Power BI Desktop、Fabric 语义模型或 PBIP/TMDL 模型，并执行语义模型查询与建模操作。

官方资料：

GitHub：https://github.com/microsoft/powerbi-modeling-mcp
npm 包：@microsoft/powerbi-modeling-mcp

触发场景

在用户提出以下需求时使用本技能：

安装、配置或排查 Power BI Modeling MCP；
连接 Power BI Desktop 中当前打开的 PBIX；
读取表、列、度量值、关系或模型元数据；
创建或修改表、列、度量值、关系、层级、格式或 TMDL；
连接 Fabric Workspace 或 PBIP/TMDL 文件夹。

执行原则

先检查现有安装和配置，避免重复安装或替换可用方案；
安装前核对 Microsoft 官方最新文档，不猜测版本、下载地址或启动参数；
根据操作系统、已有运行环境和用户要求选择官方支持的启动方式；
修改配置时保留其他 MCP 服务，不覆盖完整配置文件；
配置完成后必须实际验证服务、实例发现和模型连接，不能只检查进程是否启动；
默认先执行只读查询，未经用户明确确认不修改模型。

如果用户只要求测试或体验现有连接，只进行检查、连接和只读查询，不下载、不安装、不修改配置。

安装与配置

1. 检查现有环境

检查以下内容：

~/.workbuddy/mcp.json 是否存在以及 JSON 是否有效；
是否已有 powerbi-modeling-mcp 条目；
配置中的命令、参数和本地路径是否有效；
系统中是否已有官方 MCP Server；
当前操作系统和可用运行环境。

已存在且可用时，优先复用。发现配置异常时先说明问题，再决定修复或更换方式。

2. 选择官方启动方式

根据 Microsoft 官方当前文档和用户环境选择启动方式，常见方式包括：

npm/npx

适用于已具备 Node.js 和 npx 的环境。Windows 如需通过命令解释器启动，可使用：

{
  "type": "stdio",
  "command": "cmd",
  "args": [
    "/c",
    "npx",
    "-y",
    "@microsoft/powerbi-modeling-mcp@latest",
    "--start"
  ]
}

其他平台按官方文档配置命令和参数，不直接套用 Windows 命令。

本地可执行文件

适用于已取得 Microsoft 官方发布的对应平台服务器文件，或用户明确要求使用本地文件的环境。配置前确认文件来源、平台、版本和真实路径。

Windows 配置结构示例：

{
  "type": "stdio",
  "command": "C:\\path\\to\\powerbi-modeling-mcp.exe",
  "args": ["--start"],
  "env": {}
}

以上均为候选配置方式，不预设某一种方式适用于所有环境。以官方文档、当前环境和实际连接验证结果为准。

3. 合并 WorkBuddy 配置

WorkBuddy 用户级 MCP 配置文件：

~/.workbuddy/mcp.json

处理规则：

文件不存在时创建最小合法结构 {"mcpServers": {}}；
文件有效时，仅新增或更新 mcpServers.powerbi-modeling-mcp；
文件损坏时停止操作，不得覆盖；
替换已有配置前先备份并说明变更；
不得删除或改写其他 MCP 服务；
不写入令牌、客户端密钥、证书等敏感信息；
不添加跳过确认等高风险参数，除非用户明确理解并要求。

4. 重新加载服务

写入配置后，引导用户在 WorkBuddy 的自定义 MCP 或连接器管理页面重新加载并 Trust（信任）服务。

区分以下状态：

配置文件已写入；
MCP 服务已加载；
已发现目标模型实例；
已连接语义模型；
已完成只读查询验证。

不得把前一阶段完成描述为后续阶段已经成功。

配置完成后的用户引导

配置写入后，明确提醒用户完成以下准备：

打开目标 Power BI Desktop 文件（.pbix），等待文件完全加载，并保持窗口打开；
打开 WorkBuddy 的连接器管理或自定义 MCP 页面；
找到 powerbi-modeling-mcp 连接器并点击信任；
如连接器状态没有更新，执行刷新、重新加载或重新启动相关会话；
完成上述步骤后，再执行实例发现和只读连接测试。

不要把“配置文件已写入”或“连接器已 Trust”直接描述为“模型已经连接”。

用户需要视觉指引时，可以返回“连接器设为 Trust + 打开 PBIX”的操作示意图。示意图必须标注为示意，不得冒充 WorkBuddy 的真实界面截图。若用户上传实际界面截图，基于截图进行识别、标注和说明。

连接 Power BI Desktop

1. 发现本地实例

调用连接工具的 ListLocalInstances 操作，获取当前可连接的 Power BI Desktop 实例及其真实连接信息。

禁止猜测端口；
没有发现实例时，确认 PBIX 已完全加载并保持打开；
检查 WorkBuddy、MCP Server 和 Power BI Desktop 的用户及权限上下文；
重新加载 MCP 后仍失败时，报告实例发现失败，不伪造连接。

2. 建立连接

使用 ListLocalInstances 返回的完整 connectionString 调用 Connect。连接后使用 ListConnections 确认连接名称和数据库信息。

如果存在多个实例，先根据窗口标题、文件名或用户选择确定目标，不擅自连接不明确的模型。

3. 执行只读验证

连接成功后，默认先调用表操作的 List，读取模型表列表。

推荐测试指令：

连接到 Power BI Desktop 中当前打开的语义模型，并先读取模型中的表列表，不要修改任何内容。

除非用户明确要求，否则不执行 Create、Update、Delete、Refresh、Rename 或其他写操作。

连接其他模型

Fabric：使用连接工具提供的 Fabric 连接操作，并取得必要的工作区、语义模型和授权信息；
PBIP/TMDL：使用文件夹连接操作，传入官方要求的模型目录；
XMLA/Analysis Services：使用 Connect 和受支持的连接字符串。

连接成功后先执行只读查询。涉及写操作时，确认用户意图、目标模型、权限和备份情况。

故障处理

| 情况 | 处理方式 | |---|---| | MCP 工具不可见 | 检查 JSON、服务配置、Trust 状态及配置是否已重新加载 | | ListConnections 返回空 | 先发现实例，再使用返回的真实连接信息调用 Connect | | 本地实例发现失败 | 检查 PBIX 加载状态、权限上下文、服务器版本和启动方式；不猜端口 | | 配置命令无法启动 | 核对运行环境、命令路径、官方参数和网络条件 | | 本地服务器能启动但无法连接 | 不把进程启动视为连接成功；按官方文档检查版本、平台和实例发现能力 | | mcp.json 损坏 | 停止写入，保留原文件并报告问题 | | 连接成功但查询失败 | 确认当前连接和目标模型，再进行只读重试 | | 用户只要求测试 | 不下载、不安装、不写配置、不修改模型 |

安全原则

默认从实例发现、连接确认和元数据读取等只读操作开始；
不猜测端口、版本、路径、凭据或连接信息；
不把某种 Power BI 许可证描述为所有场景的统一前置要求；
不把配置成功、服务加载、实例发现和模型连接混为一谈；
不伪造执行结果；
未经用户明确确认，不执行模型写操作。

回复要求

连接成功时，说明：

连接的目标模型；
使用的连接名称；
完成的只读验证及结果；
是否执行过模型修改。

只完成配置但尚未连接时，明确说明仍需重新加载服务、发现实例并执行连接验证。