内容
# 微软MCP PowerBI — 智能代理集成工具包
[](https://github.com/SimonLexRS/Microsoft-MCP-PowerBI)
[](https://www.npmjs.com/package/@microsoft/powerbi-modeling-mcp)
[](https://www.npmjs.com/package/@microsoft/powerbi-report-authoring-cli)
[](https://www.npmjs.com/package/@microsoft/powerbi-desktop-bridge-cli)
[](https://github.com/SimonLexRS/Microsoft-MCP-PowerBI/stargazers)
[](LICENSE)
完整的工具包，适用于智能代理（Claude、Copilot、Cursor或其他MCP客户端），用于构建**语义模型和Power BI仪表盘**，无需关闭本地Power BI Desktop实例，包括**实时编辑可视化**。
该工具包集成和记录了微软的三个官方工具（软件包归微软所有；该存储库提供配置、验证的工作流程、已知错误及其修复程序，以及复制到任何计算机的说明）：
| 组件 | 软件包 | 角色 |
|---|---|---|
| **MCP服务器** | [`@microsoft/powerbi-modeling-mcp`](https://www.npmjs.com/package/@microsoft/powerbi-modeling-mcp) | 语义模型：表、关系、DAX度量、查询 — 通过XMLA与Power BI Desktop交互 |
| **创作CLI** | [`@microsoft/powerbi-report-authoring-cli`](https://www.npmjs.com/package/@microsoft/powerbi-report-authoring-cli) | 验证PBIR文件和可视化目录 |
| **桌面桥CLI** | [`@microsoft/powerbi-desktop-bridge-cli`](https://www.npmjs.com/package/@microsoft/powerbi-desktop-bridge-cli) | 打开、**实时重新加载**和捕获打开报告的截图 |
## 功能
### 语义模型（通过MCP — 21组工具）
| 组 | 工具 | 功能 |
|---|---|---|
| 连接 | `connection_operations` | 检测本地桌面实例并连接 |
| 表和数据 | `table_operations`, `partition_operations` | 从CSV（Power Query M）创建表，刷新数据 |
| 关系 | `relationship_operations` | 创建/激活1:N和1:1关系，具有筛选方向 |
| 度量和DAX | `measure_operations`, `dax_query_operations`, `function_operations` | 创建度量，验证和执行DAX |
| 列 | `column_operations`, `user_hierarchy_operations` | 计算列，重命名，层次结构 |
| 模型 | `model_operations`, `database_operations` | 全局刷新，导出TMDL/BIM，部署到Fabric |
| 高级 | `calculation_group_operations`, `calendar_operations`, `perspective_operations`, `security_role_operations`, `culture_operations`, `object_translation_operations`, `named_expression_operations`, `query_group_operations`, `trace_operations`, `transaction_operations` | 计算组，日历，RLS，翻译，跟踪 |
### 仪表盘（通过CLI — 实时编辑）
| 命令 | 功能 |
|---|---|
| `powerbi-report-author validate <dir .Report>` | 验证PBIR文件的模式、结构、ID、角色和枚举**之前**触及桌面 |
| `powerbi-report-author catalog describe <tipo>` | 每个可视化类型的实际角色和属性（无需猜测） |
| `powerbi-desktop open <archivo.pbip>` | 在Power BI Desktop中打开项目 |
| `powerbi-desktop status` | 打开的实例、PID、报告页面 |
| `powerbi-desktop reload --pid <pid>` | **在不关闭的情况下重新加载桌面上的可视化** |
| `powerbi-desktop screenshot-all --pid <pid> --output-dir <dir>` | 捕获所有页面进行自动验证 |
## 架构
```
┌─────────────────────┐ MCP（stdio） ┌──────────────────────────┐
│ 智能代理 │ ─────────────────────────► │ powerbi-modeling-mcp │
│ （Claude / Copilot / │ │ └─► XMLA：本地端口 │
│ Cursor / 其他） │ CLI（shell） ├──────────────────────────┤
│ │ ─────────────────────────► │ powerbi-desktop-bridge │──┐
│ │ ─────────────────────────► │ powerbi-report-authoring │ │
└─────────────────────┘ └──────────────────────────┘ │
│ 编写PBIR文件（visual.json，pages.json） │
▼ ▼
┌──────────────────────────────┐ 实时重新加载 ┌──────────────────────────┐
│ 磁盘上的.pbip项目 │ ◄───────────────── │ Power BI Desktop │
│ ├─ *.Report/（可视化） │ │ （打开的文件） │
│ └─ *.SemanticModel/（TMDL） │ └──────────────────────────┘
└──────────────────────────────┘
```
## 图库 — 使用此工具包构建的仪表盘
使用此工作流程（示例数据集：2026年世界杯）由智能代理100%生成的多页面仪表盘，通过工具包自己的截图验证：
| 具有KPI、表格和切片器的摘要 | 条形图和柱形图 |
|---|---|
|  |  |
| 具有切片器和统计表格的排名 | 时间序列和分析 |
|---|---|
|  |  |
<details>
<summary>查看详细信息页面（事件和阵容表格）</summary>
</details>
## 快速入门
```bash
# 1. 要求：Windows + Power BI Desktop + Node.js 20+
npm install -g @microsoft/powerbi-report-authoring-cli @microsoft/powerbi-desktop-bridge-cli
# 2. 克隆此工具包并从文件夹打开智能代理：
git clone https://github.com/SimonLexRS/Microsoft-MCP-PowerBI.git
cd Microsoft-MCP-PowerBI
claude # .mcp.json自动激活powerbi-modeling-mcp服务器
# 3. 使用.pbip项目打开Power BI Desktop并要求智能代理：
# “列出本地的Power BI Desktop实例并连接”
```
> ⚡ **智能辅助实现：** [PROMPTS.md](PROMPTS.md#prompt-de-implementación-copiar-en-claude-o-chatgpt)
> 包括一个现成的提示，复制到Claude或ChatGPT中，安装和配置整个工具包，逐步验证。
完整的客户安装指南（Claude Code，Claude Desktop，VS Code Copilot，Cursor，通用客户端）： **[INSTALL.md](INSTALL.md)**
完整的使用手册，验证的工作流程和已知错误： **[MANUAL.md](MANUAL.md)**
现成的示例提示： **[PROMPTS.md](PROMPTS.md)**
## Claude技能
工具包包括一个**技能** ([`skills/powerbi-mcp/SKILL.md`](skills/powerbi-mcp/SKILL.md))，它教会Claude完整的工作流程，并且只有在您要求诸如“将这些数据加载到Power BI”或“创建仪表盘”等操作时才会激活。要安装：
```bash
# Claude Code — 个人技能（在所有项目中可用）
mkdir -p ~/.claude/skills/powerbi-mcp
cp skills/powerbi-mcp/SKILL.md ~/.claude/skills/powerbi-mcp/
# 或作为项目技能（与您的存储库一起版本控制）
mkdir -p .claude/skills/powerbi-mcp
cp skills/powerbi-mcp/SKILL.md .claude/skills/powerbi-mcp/
```
在Claude Code中显式调用： `/powerbi-mcp`。
## 此工具包相对于原始软件包的优势
1. **`.mcp.json`和配置文件** 已准备好适用于每个智能代理客户端（ `--skipconfirmation` 标志是必需的，但不明显 — 如果没有它，所有写入操作都会失败）。
2. **实时仪表盘工作流程** （validate → reload → screenshot），无需关闭Power BI Desktop，即可迭代可视化。
3. **记录了三个关键错误** 以及修复程序，这些错误会破坏智能代理编写的可视化渲染（参见 [MANUAL.md](MANUAL.md#errores-conocidos-y-sus-fixes) — 通过与Desktop自己的文件比较发现）。
4. **`scripts/build_visuals.py`**：使用Power BI Desktop 2.155+接受的确切格式生成PBIR页面/可视化（KPI卡，条形图，柱形图，线形图，表格，切片器）。
5. **`CLAUDE.md`** 包含代理说明：当在Claude Code中打开此存储库时，代理已经知道完整的工作流程，无需解释。
## 要求
- Windows 10/11（Power BI Desktop仅限Windows）
- [Power BI Desktop](https://aka.ms/pbidesktop) （免费，2026年6月版本+）
- [Node.js 20+](https://nodejs.org) （MCP通过`npx`运行）
- Python 3.10+（可选，仅用于`scripts/build_visuals.py`）
- 无云凭证：所有操作都在本地运行，与Power BI Desktop交互
---
**作者：** Simon Rodriguez — [LinkedIn](https://www.linkedin.com/in/srodriguezxs/)
集成的npm软件包归微软所有。本工具包根据[MIT](LICENSE)许可证分发。
