AI导哈

Power BI MCP服务器

Power BI MCP服务器是一款企业级模型上下文协议服务器，用于连接AI助手与Power BI内容，提供安全、治理和操作功能，适用于Power BI Desktop、Power BI服务和PBIP文件。

  • by sulaiman013
  • Python
  • 本地部署
  • 116 星标
  • 更新于
在 GitHub 查看 sulaiman013/powerbi-mcp

使用说明

Power BI MCP服务器

An enterprise-grade Model Context Protocol server for Power BI and Microsoft Fabric.

Let AI assistants inspect, query, validate, optimize, govern, and safely refactor Power BI semantic models and reports, through natural language.

免责声明： 这是一个独立的社区项目。它不隶属于、不认可 由微软公司或Anthropic提供或与之相关。

它是什么

Power BI MCP服务器将AI助手（Claude、GitHub Copilot、任何MCP客户端）连接到您的 通过一个一致的界面为BI内容供电。它与本地Power BI Desktop模型进行对话， 已发布的Power BI服务数据集或磁盘上的Power BI项目（PBIP）文件，并包装每个 安全和治理层中的操作。

它暴露了 78工具 加MCP 资源, 提示，以及 完成和船 23个基于断言的测试套件。

能力 你得到了什么
双重连接 Power BI桌面（本地）和Power BI服务（云）
自然语言DAX 通过对话运行、验证和优化DAX
安全重构 基于PBIP的重命名，用于更新模型 和 报告视觉效果
批量DAX创建 离线或实时编写的测量套件生成器（时间智能、比率、排名）
数据建模 日期维度生成器、计算组、层次结构、离线TMDL编写
仓库审核 星型模式分类+发现，参考完整性孤儿扫描
报告编写（预览） 从代理向PBIR报告添加页面、视觉效果和字段绑定
DAX安全循环 提交前验证；影响分析；原子事务
模型质量 最佳实践分析器、人工智能就绪度评分、VertiPaq式存储分析
诊断和操作 刷新故障分类、未使用对象检测、RLS测试矩阵
治理 强制PII和列策略、防篡改审计、只读模式
车队（管理员） 跨工作区沿袭、车队刷新监控、使用情况分析
现代MCP 工具注释、结构化输出、资源、提示、完成

你能用它做什么（简单地说）

这台服务器是一座桥梁。人工智能助手本身只能说话。这给了它一套 “手”，这样它就可以进入Power BI，真正为您完成工作。你直截了当地问 英语，助手选择正确的工具，你会得到答案或改变。

它插入三个位置：

  1. Power BI桌面：该应用程序在您的PC上打开。它与其中的实时模型进行对话。
  2. Power BI服务：云、您发布的数据集和工作区。
  3. PBIP文件：保存“Power BI项目”时，模型和报告将变为文本文件 即使在关闭桌面的情况下，它也可以直接编辑磁盘上的内容。

下面使用的几个术语：A 语义模型 （数据集）是报告背后的数据大脑 （其表、列、关系和度量）。A. 测量 是已保存的计算 书写于 DAX 指数 （Power BI的公式语言）。 不宁腿综合征 是行级安全（规则 限制用户可以看到的行）。

你可以要求它做的事情

  • 了解一个你从未见过的模型。 列出表、列、度量值（带公式）， 或者一次了解全局。

    “连接到我的Power BI桌面并总结模型。”

  • 用简单的英语查询您的数据。 它将问题转换为DAX并运行它。

    “上个季度销售额排名前十的产品是什么？”

  • 安全地编写、修复和优化措施。 它根据您的模型验证DAX 之前 节省资金，因此可以及早发现损坏的公式。它还可以解释或加速一项措施。

    创建“利润率%”度量，即利润除以销售额，格式为百分比

  • 在不破坏报表的情况下重命名表、列或度量值。 仅修复普通工具 模型和视觉效果都被破坏了。这将同时更新模型和报告视觉效果， 作为一个在任何事情失败时回滚的事务。

    将表“Salesforce_Data”重命名为“Sales Force Data”

  • 在你改变任何事情之前，先看看会发生什么。 全爆炸半径：每个测量值 这取决于对象和使用它的每个报表可视化。

    “如果我删除‘旧收入’指标，这取决于什么？”

  • 管理关系 表之间（基数和过滤方向）。
  • 构建报告页面和视觉效果（预览）。 在已保存的PBIP项目上，它可以添加页面，删除 图表、卡片、表格或切片器，并按角色绑定字段。它检查每个字段是否存在于 首先，模型自动选择度量值与聚合列，并写入Power BI忠实值 PBIR文件（一直到 nativeQueryRef 和 Sum(...) 查询参考桌面本身写入）。

    在PBIP项目中，添加一个“概述”页面，其中包含按地区划分的销售柱状图

  • 像高级评审员一样检查模型质量。 最佳实践分析器（性能、DAX、， 命名、格式化）、AI就绪度评分、存储/大小分析和查询性能提示。

    “审核这个模型，并在发货前给我解决的首要问题。”

  • 批量创建受治理的度量值套件。 将一个基本指标扩展为全职情报 集合（年初至今、季度、MTD、PY、同比、同比百分比、月环比百分比、滚动窗口）、占总比率的份额、排名或 列统计。每个度量值都有一个格式字符串、显示文件夹和描述， 并且可以离线直接写入PBIP文件，也可以在一个经过验证的批中实时创建。

    “为[日期]期间的‘总销售额’生成全职智能套件，并将其添加到模型中。”

  • 构建数据仓库主干。 生成一个完整的、标记日期的维度表 （带排序的月/季度标签和可选的会计列），创建计算组 （测量爆炸的专业替代方案），并添加深入层次结构，所有 离线进入PBIP项目。

    “创建一个2018年至2030年的日期表，其中包含7月份的财政年度和时间情报计算组。”

  • 将模型作为星型模式进行审核。 对每个表进行分类（事实、维度、日期维度、， 桥接，断开连接）与关系拓扑的连接，并标记雪花链，双向 过滤器、多对多、事实对事实连接、缺失或未标记的日期表以及文本属性 被困在事实上，每个发现都有一个分数和一个修复。

    “将我的模型作为星型模式进行审核，并告诉我仓库架构师会标记什么。”

  • 在孤儿密钥扭曲总数之前将其捕获。 使用扫描每个关系以查找事实密钥 没有匹配的维度行（隐藏空白行的原因）。

    “扫描引用完整性，并向我展示每个关系的孤儿密钥示例。”

  • 在DAX指数中寻找性能陷阱。 静态分析器标记经典反模式 （在CALCULE、嵌套CALCULE中过滤整个表， / 代替DIVIDE、IFERROR， 早期，SUMMARIZE用于聚集、空白抑制 + 0，未被识别或 产生幻觉的函数名），并为每个函数重新编写具体的代码。

    “梳理我模型中的每一项指标，并为最糟糕的违规者提出重写建议。”

  • 规范整个模型的命名。 审核表、列和度量值名称，并获取 重命名平面图（蛇形外壳和驼色外壳为间隔的标题外壳，带DIM_/FACT_前缀，装饰 空格），然后使用也修复报告视觉效果的安全重命名工具应用它。

    “审核命名并将所有内容重命名为Title Case，而不会破坏报告。”

  • 使用一个DAX指标添加微观视觉效果。 生成火花线、项目符号图、进度条， 或将状态药丸作为内联SVG度量，直接在表、矩阵或卡片内呈现。

    “为我制作一个进度条，用于衡量‘利润率%’与100%目标之间的差距。”

  • 打开一个真实 .pbix 文件。 检查a .pbix （这是一个ZIP包）：看看它是否有 导入的模型或实时连接，它使用哪种报告格式，以及有多少页，然后 提取它并将报告布局解码为可读的JSON。

    “检查这个.pbix，告诉我它是否有导入的模型以及有多少页。”

  • 制定并管理自己的质量规则。 验证自定义最佳实践分析器规则 设置（捕获错误的作用域、重复的ID、有风险的自动删除）并审核规则实际所在的位置： 嵌入模型、忽略或从外部文件中提取。

    “验证我们的BPARules.json，并告诉我此模型正在默默忽略哪些规则。”

  • 清理自重。 查找未使用的列和度量值（不在任何公式中） 而且没有任何视觉效果），这样你就可以安全地清除杂乱。
  • 正确测试安全角色。 在每个RLS角色下运行一个度量，并获得通过/失败 标记角色看到太多或什么都看不到的矩阵。
  • 自动记录模型。 生成一个数据字典（Markdown或HTML） 文档覆盖率得分，可随时重新运行。
  • 比较版本和网关部署。 对模型进行快照，稍后进行比较以确保可读性 “更改内容”列表，运行预部署PASS/FAIL质量门，并运行DAX回归测试。
  • 对刷新（云）进行故障排除。 当刷新失败时，它会对原因进行分类（过期 凭据、网关关闭、节流、内存不足、超时、错误的源查询）和告诉 你解决。
  • 管理访问权限并保持合规。 在AI看到之前屏蔽PII，阻止/屏蔽/哈希/编校 特定列，保留防篡改审计日志，并打开只读模式，以便代理可以 看，但不要碰。
  • 查看整个租户（管理员）。 清点每个工作区，找到没有的数据集 安全或无敏感标签，跟踪哪些报告使用数据集，监控刷新健康状况， 并查看使用情况分析。

一个现实的端到端示例

  1. “连接到我的Power BI桌面模型。”
  2. “审核并列出最糟糕的问题。”
  3. “如果重命名“客户ID”列，会出现什么问题？”
  4. “跨模型和报表将其重命名为”CustomerKey“。”
  5. “创建一个‘同比销售额百分比’指标，验证它，并将其格式化为百分比。”
  6. “导出数据字典，以便团队有文档。”
  7. “在发布之前运行预部署质量门。”

每一步都是一句话；服务器在其背后执行真正的Power BI工作。

为什么选择此服务器

微软现在发布官方Power BI MCP服务器（公开预览版）：一个远程服务器 与数据聊天和创建语义模型的本地建模。这个项目是 互补的。它倾向于这些服务器没有覆盖的内容：

  • 报告安全重命名。 官方本地建模MCP仅编辑模型 无法触摸报表层。此服务器重命名表、列和度量值 模型（TMDL）和报告（PBIR视觉效果、文化、图表），因此视觉效果不会中断。
  • 真正的治理和安全层。 强制列策略（块、掩码、哈希、， redact、数字掩码）、PII检测、防篡改审计日志和只读锁定模式。
  • 诊断和车队运营。 刷新故障分类、未使用对象清理、影响 分析、RLS测试矩阵和租户范围的沿袭和使用分析。
  • 离线，PBIP优先工作流。 整个PBIP、分析和安全子集都在运行 跨平台，无需结构容量。

看 docs/ARCHITECTURE.md 因为它是如何结合在一起的。

快速启动

先决条件

实时连接（Power BI桌面/服务）： Windows 10/11，Power BI桌面，Python 3.10+， 以及ADOMD。NET客户端库。较新的Power BI Desktop版本不再提供ADOMD。NET，所以 安装SQL Server Management Studio（Contoso）或 Microsoft.AnalysisServices.AdomdClient NuGet包或点 ADOMD_DLL_PATH 在包含以下内容的文件夹中 Microsoft.AnalysisServices.AdomdClient.dll。服务器搜索Power BI桌面、ExpressRoute、 SQL Server SDK和NuGet自动运行。云还需要Azure AD服务主体， 对于某些操作，高级/PPU/结构容量。

仅限离线子集（PBIP编辑、BPA、分析、安全）： 任何操作系统，Python 3.10+，没有。网。

安装

git clone https://github.com/sulaiman013/powerbi-mcp.git
cd powerbi-mcp

# Full install (Windows, for live connectivity)
pip install -r requirements.txt

# Or: offline / cross-platform subset only
pip install -r requirements-core.txt

# (Optional) cloud credentials, Windows
copy .env.example .env
# edit .env with your Azure AD service principal

配置Claude桌面

添加到 %APPDATA%\Claude\claude_desktop_config.json，然后重新启动Claude Desktop：

{
  "mcpServers": {
    "powerbi": {
      "command": "python",
      "args": ["C:/path/to/powerbi-mcp/src/server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/powerbi-mcp/src"
      }
    }
  }
}

使用Docker运行（离线、跨平台）

该图像运行独立于平台的工具（PBIP编辑、BPA、AI就绪、模型分析、， 安全、资源、提示）。网。实时桌面/XMA/TOM连接 仍然需要Windows+ADOMD。网。

docker build -t powerbi-mcp .
docker run --rm -i -v /path/to/MyReport:/work powerbi-mcp

工具

以下类别共有78种工具。完整的参考，包括参数和读/写/ 破坏性标记 docs/TOOLS.md.

类别 计数 亮点
桌面（本地、ADOMD） 7 发现、连接、列出表/列/度量值， desktop_execute_dax，型号信息
云（XMLA+REST） 6 工作区、数据集、表、列、， execute_dax，型号信息
安全和审计 3 security_status, security_audit_log, verify_audit_integrity
行级安全 3 列出角色、设置角色、状态
模特写作（TOM） 7 create_measure, delete_measure, batch_update_measures，已弃用的批重命名
DAX安全和交易 5 validate_dax, scan_measure_dependencies，开始/提交/回滚事务
关系 2 create_relationship, delete_relationship
PBIP安全编辑 5 加载项目，获取信息，重命名表/列/度量值（模型+报告）
PBIP诊断 4 修复损坏的视觉效果，修复DAX报价，扫描损坏的引用，验证
报告编写（PBIR、预览） 4 pbir_add_page, pbir_add_visual, pbir_bind_fields, pbir_validate_report
模型质量和性能 4 run_bpa, audit_ai_readiness, analyze_model_storage, analyze_query_performance
DAX质量 2 dax_lint （性能反模式）， dax_suggest_rewrite
创作助手 2 generate_svg_measure （火花线/子弹/进步/药丸）， audit_naming
PBIX入职培训 2 pbix_inspect, pbix_extract （打开一个真实的 .pbix)
自定义BPA治理 2 bpa_validate_rules, bpa_audit_rule_sources
批量DAX创建 3 generate_measure_suite, batch_create_measures, pbip_add_measures
数据建模（离线TMDL） 3 pbip_create_date_table, pbip_add_calculation_group, pbip_add_hierarchy
仓库审核 2 audit_star_schema, scan_referential_integrity
文档、差异、CI 5 export_data_dictionary, model_snapshot, model_diff, pre_deploy_gate, run_dax_tests
诊断和操作 4 refresh_doctor, find_unused_objects, impact_analysis, rls_test_harness
治理运营团队（管理员） 3 cross_workspace_lineage, fleet_refresh_monitor, usage_and_orphan_analytics

资源、提示和完成

  • 资源： powerbi://desktop/{schema,measures,bpa,ai-readiness}, powerbi://cloud/{workspace}/{dataset}/schema, powerbi://reference/{bpa-rules,refresh-errors}.在不调用工具的情况下附加模型上下文。
  • 提示： optimize_measure, explain_measure, audit_model, document_model, plan_safe_rename, pre_deploy_review。现成的、工具编排的剧本。
  • 完成： 从中获取真实表和度量值名称中的理由提示和资源参数 连接模型。
  • 注释和结构化输出： 每个工具都声明了安全提示 (readOnlyHint, destructiveHint)；键入关键工具 structuredContent.

安全重命名：两层问题

Power BI分别存储模型层和报告层。TOM（以及官方建模MCP） 可以编辑模型，但不能更新报告视觉效果，因此TOM重命名会使视觉效果指向 旧名字。此服务器通过以下方式解决了这个问题 PBIP文件编辑：它重写TMDL模型文件 将PBIR报告文件（视觉绑定、区域性、图表）放在一起，这样就不会有任何损坏。

User: "Load PBIP project from C:/Projects/SalesReport"
User: "Rename table Salesforce_Data to Sales Force Data"

重命名级联是事务性的（它在失败时回滚每个文件），并以原子方式写入 （临时文件加 os.replace)，保留编码和行尾。

总是 使用 pbip_rename_* 重命名工具，而不是弃用的TOM batch_rename_* 工具。在PBIP编辑之前关闭Power BI Desktop，然后重新打开。

安全和治理

  • PII检测和屏蔽 在结果到达AI之前（SSN、信用卡、电子邮件、电话、IP）。
  • 强制的列和表策略 从 config/policies.yaml: block, mask, hash, redact，以及 numeric_mask （会话随机缩放，隐藏值但保留比率）。
  • 审计日志 具有防篡改哈希链；用以下方式进行验证 verify_audit_integrity. 集 POWERBI_MCP_AUDIT_KEY 将链切换到HMAC-SHA256（密码学上对 编辑日志的攻击者）；如果没有密钥，它仍然是一个简单的SHA-256链 意外编辑和天真篡改。
  • 只读/锁定模式： 集 POWERBI_MCP_READONLY=true 拒绝所有书写工具 （模型/报告突变 和 文件写入工具，如快照、字典和PBIX 提取），同时读取和诊断继续工作。非常适合共享或自主代理使用。
  • 从日志、错误消息、审核日志和 每个工具响应（编校应用于响应边界，而不仅仅是每个处理程序）。
# config/policies.yaml (excerpt)
tables:
  - name: "*"
    columns:
      - name: ssn
        action: block
      - name: card_number
        action: mask

环境变量

变量 目的
TENANT_ID, CLIENT_ID, CLIENT_SECRET Azure AD服务主体（云、REST、管理员）
ADOMD_DLL_PATH 文件夹（或完整路径） Microsoft.AnalysisServices.AdomdClient.dll，如果自动发现错过了它
POWERBI_MCP_READONLY true 拒绝所有写入工具（锁定模式）
POWERBI_MCP_AUDIT_KEY 将审计哈希链切换到HMAC-SHA256（更强的防篡改性）的密钥
ENABLE_PII_DETECTION, ENABLE_AUDIT, ENABLE_POLICIES 切换安全子系统（默认为真）
LOG_LEVEL DEBUG 启用编辑参数日志记录

文档

文档 目录
docs/TOOLS.md 所有78个工具、资源、提示、环境变量的完整参考
docs/ARCHITECTURE.md 组件、安全层、注册表模式、验证方法、文件映射
docs/TEST.md 如何经营套房以及每套套房涵盖的内容
更改日志.md 一切都改变了，按里程碑
代理商.md 代理手册：黄金法则、工作流程、DAX模式

测试

套房在 tests/ 是基于断言的脚本，在没有Power BI的情况下运行（测试纯逻辑 直接；模拟带电连接器）。

python run_tests.py

看 docs/TEST.md 每套套房的价格。实时桌面、XMLA、REST和 管理员路径经过Microsoft Learn的文档验证和模拟测试；端到端验证 这些路径需要Windows+Power BI/Fabric环境。

项目结构

powerbi-mcp/
├── src/
│   ├── server.py                    # MCP server: 78 tools + resources/prompts/completion
│   ├── powerbi_desktop_connector.py # Desktop (ADOMD) + RLS + VertiPaq DMVs
│   ├── powerbi_xmla_connector.py    # Cloud XMLA
│   ├── powerbi_rest_connector.py    # REST: discovery, refresh, admin Scanner/Activity
│   ├── powerbi_tom_connector.py     # TOM writes: measures, relationships, transactions
│   ├── powerbi_pbip_connector.py    # PBIP/TMDL/PBIR offline editing (transactional)
│   ├── pbir_authoring.py            # PBIR emitters: pages, visuals, field projections
│   ├── adomd_loader.py             # Shared ADOMD.NET discovery (Desktop + XMLA)
│   ├── model_analysis.py            # BPA, AI-readiness, data dictionary, diff, DAX tests
│   ├── dax_lint.py                  # DAX anti-pattern linter + rewrite hints (tokenizer)
│   ├── svg_measures.py             # SVG micro-visual DAX measure generators
│   ├── naming_audit.py             # Naming-convention audit -> rename plan
│   ├── pbix_tools.py               # PBIX (.pbix ZIP) inspect/extract + layout decode
│   ├── bpa_authoring.py            # Custom BPA rule validation + rule-source audit
│   ├── dax_generator.py            # Bulk measure-suite generation (time intel, ratios, ranks)
│   ├── star_schema.py              # Star-schema classification + warehouse audit
│   ├── tmdl_authoring.py           # TMDL emitters: measures, date table, calc groups, hierarchies
│   ├── refresh_diagnostics.py       # Refresh error classification
│   ├── governance.py                # Scanner summary + activity aggregation
│   └── security/                    # security_layer, access_policy, pii_detector, audit_logger
├── config/policies.yaml
├── tests/                           # Assert-based suites
├── docs/                            # TOOLS, ARCHITECTURE, TESTING
├── run_tests.py
├── AGENTS.md, CLAUDE.md
├── Dockerfile, requirements-core.txt
├── pyproject.toml, .editorconfig
├── CHANGELOG.md, requirements.txt
└── README.md

局限性

限制 注意事项
实时连接仅适用于Windows ADOMD。NET和TOM需要Windows。离线子集通过Docker跨平台运行。
TOM重命名break视觉效果 使用PBIP工具进行安全重命名（它们也会更新报告层）。
云增强刷新需要高级 XMLA，增强刷新需要PPU/高级/Fabric容量。Pro上的基本刷新和历史记录工作。
车队治理由管理员控制 扫描程序和活动工具需要结构管理员，或者允许服务主体使用只读管理API。
深度服务器计时 analyze_query_performance 给出持续时间和提示；使用DAX Studio进行存储与配方引擎计时。

路线图

完成

  • Power BI桌面和服务连接、RLS测试、TOM写入、PBIP安全编辑。
  • DAX在提交循环、原子事务、依赖关系和影响分析之前进行验证。
  • 最佳实践分析器、人工智能就绪度评分、VertiPaq风格的存储和查询分析。
  • 事务性、原子性、编码忠实的PBIP重命名。
  • 强制列策略、PII屏蔽、数字屏蔽、防篡改审计、只读模式。
  • 文档导出、模型快照和差异、预部署门、DAX回归运行器。
  • 刷新医生，未使用对象检测，RLS测试矩阵。
  • 跨工作区沿袭、车队刷新监控、使用情况分析。
  • 现代MCP界面：注释、结构化输出、资源、提示、完成。
  • 跨平台离线子集的Docker镜像。

计划的

  • 使用Microsoft Entra OAuth进行远程HTTP传输（今天，使用官方远程Power BI MCP 云认证服务器）。
  • 最佳实践分析器自动修复和自定义团队规则包。
  • 更深入的VertiPaq（每列基数）和服务器计时捕获。
  • 可选的本地/开源LLM支持。

贡献

  1. 分叉存储库。
  2. 创建要素分支。
  3. 保持工具注册表同步（工具位于 handle_list_tools, _build_tool_dispatch, 和 _build_tool_annotations 在 src/server.py；奇偶校验强制执行此操作）。
  4. 跑 python run_tests.py 并保持所有套房的绿色。
  5. 打开一个pull请求。

格式约定在 pyproject.toml 和 .editorconfig.

作者

苏莱曼·艾哈迈德数据分析工程师和微软认证专家。

许可证

MIT。看 许可证.

致谢

  • 模型上下文协议 通过Anthropic。
  • 微软的TOM、TMDL和PBIR文档。
  • Power BI社区，了解PBIP格式和语义模型最佳实践。

相关 MCP