Power BI Unified MCP

一个用于 AI 驱动的 Power BI 语义模型工程和 PBIR/PBIP 报表创作的统一 MCP 接口。

语义模型操作通过 Microsoft 的 Power BI Modeling MCP 执行。本项目在单个 MCP 服务器后面增加了统一编排、本地 PBIR/PBIP 报表创作、安全控制、诊断以及 stdio/HTTP 传输。

状态：Early Release / Public Preview - v0.2.0

Power BI 是 Microsoft 的产品。本仓库并非 Microsoft 所有，不捆绑 Microsoft 的建模可执行文件，也不是 Power BI Desktop 的完整替代品。

存在的原因

Power BI 自动化目前横跨两个不同的层面：

• 针对 Power BI Desktop 或兼容表格模型的语义模型工程

• 磁盘上的 PBIR/PBIP 报表定义编辑

本项目将这两个层面整合在一起，使 AI 客户端可以通过一个 MCP 工具目录检查、验证和修改报表与模型，同时仍然遵守本地安全控制。

Related MCP server: powerbi-mcp-local

与 Microsoft 的 Modeling MCP 有何不同

Microsoft 的 Modeling MCP 专注于语义模型操作，例如连接、表、列、度量值、关系、DAX、角色、分区、TMDL 以及相关的元数据工作。

powerbi-unified-mcp 保留了上游能力，但增加了：

• 本地 PBIR/PBIP 报表项目发现和生命周期管理

• 页面和视觉对象创作

• 字段绑定和格式设置

• 主题、筛选器、交互、验证、检查点和撤销

• 一个合并的 MCP 界面，用于报表和模型工作

• 本地策略执行、诊断、审计日志和功能报告

当前范围

v0.2.0 目前可以做到：

• 发现并打开 PBIR/PBIP 报表项目

• 创建、重命名、复制和删除报表页面

• 创建、检查、移动、调整大小、更改类型、绑定和格式化支持的视觉对象

• 应用主题、设置筛选器、配置视觉对象交互，并验证报表结构

• 创建报表检查点、恢复检查点，以及撤销最近的报表更改

• 代理来自 Microsoft 的 Modeling MCP 的语义模型操作

• 通过上游工具系列支持本地 Power BI Desktop 发现、连接、DAX 验证/执行和临时度量值 CRUD

• 使用官方 MCP SDK 提供 stdio 和 HTTP 传输

目前还不能做到：

• 在没有 PBIR/PBIP 项目的情况下直接对实时 .pbix 画布进行修改

• 完整的 Power BI Service 或 Fabric 生命周期管理

• 书签修改或完整的按钮/导航创作

• 完整的条件格式抽象

• 支持所有原生或自定义 Power BI 视觉对象

• 作为成品提供托管多用户部署、身份验证或 RBAC

架构

flowchart TD
    A[AI Client / MCP Host] --> B[Power BI Unified MCP]

    B --> C[PBIR/PBIP Report Authoring Engine]
    B --> D[Microsoft Power BI Modeling MCP]

    C --> E[Pages]
    C --> F[Visuals]
    C --> G[Field Bindings]
    C --> H[Formatting]
    C --> I[Themes]
    C --> J[Filters & Interactions]
    C --> K[Validation & Checkpoints]

    D --> L[Power BI Desktop / Fabric Semantic Model]

    L --> M[Tables & Columns]
    L --> N[Measures & DAX]
    L --> O[Relationships]
    L --> P[Partitions]
    L --> Q[RLS / Security Roles]
    L --> R[Calculation Groups]
    L --> S[TMDL / TMSL]

通俗易懂的划分：

• 报表创作在本仓库中实现，作用于磁盘上的 PBIR/PBIP 项目。

• 语义模型工程委托给 Microsoft 的外部 Modeling MCP，然后通过兼容性检查、策略执行、诊断和审计日志进行包装。

更多详情：架构

快速安装

git clone <repo-url>
cd powerbi-unified-mcp
npm install
npm run build
npm test

如果 Microsoft Modeling MCP 未被自动发现：

$env:POWERBI_MODELING_MCP_EXE="C:\path\to\powerbi-modeling-mcp.exe"

以 stdio 模式运行：

node server.js

以 HTTP 模式运行：

node server.js --transport=http --port=8765

健康检查：

curl http://127.0.0.1:8765/health

完整设置：安装

MCP 客户端示例

• 通用 MCP 客户端

• Codex

• Claude

• ChatGPT

示例提示词

检查我当前打开的 Power BI Desktop 模型，并汇总表、度量值和关系。

创建一个 Total Profit 度量值，验证 DAX，并查询它以确认其正常工作。

打开此 PBIR 报表项目，并列出报表页面、视觉对象和活动主题。

创建一个 Executive Overview 报表页面，包含 Total Sales 和 Profit 卡片、月度销售趋势、类别销售条形图以及一个 Region 切片器。

找到 Sales by Category 视觉对象，将其更改为簇状条形图，移动到页面右侧，并验证报表。

验证当前 PBIR 报表，并在修改任何内容之前解释所有错误。

安全

安全模式：

• read-only

• safe-write

• full

重要默认值：

• 报表修改被限制在配置的文件系统根目录内

• 大多数报表写入默认创建自动检查点

• 破坏性或安全敏感的建模操作受策略门控

• HTTP 模式是开发传输方式，应视为本地优先

不要在未经身份验证、TLS、反向代理、日志记录和网络保护的情况下公开暴露 full 模式端点。

更多详情：安全模型

兼容性

• Node.js >=20

• Windows 是实时 Power BI Desktop 集成的主要支持环境

• 语义模型功能需要 Microsoft 的 Power BI Modeling MCP

• 支持的最低上游 Modeling MCP 版本：0.4.0

• v0.2.0 已针对真实的 Power BI Desktop 模型进行了实时测试，涵盖发现、连接、元数据检查、DAX 验证/执行以及带清理的临时度量值 CRUD

更多详情：Modeling MCP 兼容性

限制

• 直接编辑 .pbix 画布不是报表创作路径；请使用 PBIR/PBIP 项目

• 语义模型功能依赖于 Microsoft 的上游可执行文件

• 实时 Desktop 集成以 Windows 为重点

• 报表视觉对象覆盖范围相当广泛，但尚不完整

更多详情：限制

文档

• 文档主页

• 快速入门

• Power BI Desktop

• 语义建模

• 报表创作

• 视觉对象目录

• 配置参考

• 工具参考

• 生成的能力矩阵

• 故障排除

• 路线图

贡献

贡献者设置、测试流程、元数据生成和发布预期：CONTRIBUTING.md

许可证

MIT。请参阅 LICENSE。