# Claude Power BI MCP + Skill

> Claude Power BI MCP + Skill — 让 Claude Code 直接读写 Power BI 数据模型

---

## 背景与目的

### 行业现状：生态概览

截至 2026 年 7 月，Power BI 与 AI 助手的集成主要有以下路径：

| 方案 | 类型 | 连接方式 | 修改能力 |
|------|------|----------|:---:|
| **官方 Power BI MCP (Preview)** | 官方 | 本地建模 / 云端查询 | **读写 + 查询** |
| **社区 Power BI MCP** | 社区开源 | REST API / 本地 SSAS | 仅读取 |
| **本方案 (Claude Power BI MCP + Skill)** | 社区开源 | 本地 SSAS (ADOMD.NET + TOM) | **读写 (TOM)** |

### 关键发现

1. **官方 Power BI MCP (Preview) 已发布** — 包含 local（建模读写）和 remote（查询分析）两类服务，认证要求视连接目标而定
2. **社区方案存在，但功能有限** — 可读取模型元数据，但**均不支持修改 Measure**
3. **ChatGPT/Copilot 可通过官方 MCP server 及 Copilot for Power BI 读写模型** — 但这些能力绑定在 ChatGPT/Copilot 生态中，Claude Code 用户无法直接使用

### 功能比对

| 能力 | 官方 MCP | 社区 MCP | 本 MCP |
|------|:---:|:---:|:---:|
| **读取模型** | 支持 | 支持 | 支持 |
| **修改 Measure** | 支持 (TMDL) | 不支持 | **支持 (TOM)** |
| **创建/删除 Measure** | 支持 | 不支持 | **支持** |
| **创建表/列** | 支持 | 不支持 | **支持** |
| **执行 DAX** | 支持 | 支持 | 支持 |
| **全文搜索 DAX** | 未提及 | 部分支持 | **全文搜索** |
| **审计 Power Query** | 未提及 | 不支持 | **支持** |
| **关系管理** | 支持 | 不支持 | **支持** |
| **安全角色查看** | 支持 | 不支持 | **支持** |
| **事务批处理** | 支持 | 不支持 | **支持** |
| **模型拓扑图** | 支持 | 不支持 | **支持** |
| **自动发现实例** | 支持 | 需配置 | **零配置** |
| **认证要求** | 视场景而定 | Azure AD | **无需认证** |
| **运行环境** | Node.js 20+ | Python | Python |
| **部署方式** | npx + 配置 | 手动配置 | **发给 Claude 一句话** |
| **离线可用** | 视场景而定 | 混合 | **是** |

### 实际使用场景

数据团队在日常 Power BI 开发中面临：

1. **模型规模大** — 大型 PBIX 文件可能包含数百个 Measure，手动维护成本高
2. **列名变更频繁** — 底层数据源字段重命名后，需要快速定位所有受影响的 Measure
3. **跨 Measure 搜索** — Power BI Desktop 不支持在 DAX 公式中全局搜索关键字，需要借助 Tabular Editor、DAX Studio 等外部工具
4. **批量修改需求** — 当列名变更时，需要逐个手动修改受影响的 Measure，效率低且容易遗漏
5. **AI 模型因素** — 团队以 Claude Code 为日常工具，ChatGPT/Copilot 的官方 Power BI MCP server 无法在 Claude 生态中使用

### 为什么内部推广

- **统一工具链** — 团队已使用 Claude Code，无需切换到 ChatGPT/Copilot
- **一句话部署** — 非技术人员只需把 GitHub 链接发给 Claude，全自动完成
- **Token 和时间双节省** — 相比逐层解压 PBIX 的手工方式，工具化调用将分析时间从数十分钟缩短至秒级
- **可复用** — 适用于任何使用 Power BI Desktop 的团队和项目

---

## 部署方式

### Claude 自动部署（推荐 ✨）

**把以下内容发给 Claude Code，Claude 会自动完成全部部署：**

> 请帮我从 GitHub 下载并部署 Claude Power BI MCP：
> https://github.com/WenfengGu/Claude-PowerBI-MCP
>
> 1. 下载 main.zip 并解压到 %USERPROFILE%\Claude-PowerBI-MCP
> 2. 运行 pip install pythonnet
> 3. 自动检测 Power BI Desktop 安装路径
> 4. 生成 .mcp.json 配置文件
> 5. 安装 Power BI Skill 到 ~/.claude/skills/
> 6. 运行 test_connection.py 验证

Claude 执行完毕后，打开 PBIX 文件即可使用。

### 部署后发生了什么？

```
┌─────────────────────────────────────────────────┐
│  Skill 层: 自动触发                              │
│  触发词 → 自动调用 Power BI 工具                  │
├─────────────────────────────────────────────────┤
│  MCP Server 层: 21 个工具                        │
│  discover · get_measures · search_dax            │
│  replace_in_measure · run_dax · create_measure   │
│  get_power_query · audit_power_query             │
│  batch_operations · get_model_graph              │
├─────────────────────────────────────────────────┤
│  SSAS 层: ADOMD.NET + TOM                       │
│  localhost → Power BI Desktop                   │
└─────────────────────────────────────────────────┘
```

---

## 能做什么？

### 读懂你的模型

看一眼就能了解整个模型结构：

```
"帮我看看这个模型有哪些表，多少 Measure"
→ 列出所有表、Measure 数量和 DAX 公式，秒级出结果
```

### 找到隐藏的依赖

数百个 Measure 中，哪些引用了某个列？Power BI Desktop 做不到，但 Claude 可以：

```
"搜索所有 DAX 中引用了某个列的 Measure"
→ 受影响 Measure 逐个列出，高亮匹配行
```

### 批量修改，一步到位

列名变了？不用手动改几十个 Measure：

```
"把所有 Measure 里的字段名 A 替换成字段名 B"
→ 全部 Measure 自动修复
```

### 理解业务逻辑，写对 DAX

不是简单地拼 DAX，而是先理解模型已有的业务定义：

```
"建一个 MTD 新客指标"
→ 先搜索模型里已有的 [NEW CLIENTS] 和 ISFIRSTTRANSACTION 逻辑
→ 确认理解后再创建：TOTALMTD([NEW CLIENTS], 'Calendar'[DATE])
→ 放在 ClaudeTest 文件夹，方便你验证
```

### 审计 Power Query，给出优化建议

```
"审计我的 Power Query"
→ 发现查询折叠缺失、高复杂度步骤等优化机会
→ 给出具体的改进建议和示例代码
```

### 执行 DAX，验证数据

```
"RETAIL 渠道今年销售额是多少？"
→ 即席查询，秒级返回结果
```

### 创建和修改，不只是读

```
"创建一个表，包含 Store 和 Sales 列，再加一个 SUM measure"
→ 创建 Claude Demo 表 + 2 列 + Measure，一气呵成

"把这 3 个 Measure 打包成一个事务操作，失败就全部回滚"
→ batch_operations，原子性保证
```

### 业务分析洞察

一句话，自动拉取多个维度的数据，给出结构化分析报告：

```
"给我一份上个月的销售绩效总结"
→ 月度快照 (MoM/YoY)
→ 渠道分析
→ 品类分析
→ 新客分析
→ YTD 累计
→ 关键结论和洞察
```

---

## 常见问题

### Q: 提示 "No Power BI Desktop instances found"
**A:** 确保 Power BI Desktop 正在运行，且打开了一个 PBIX 文件。

### Q: 提示 "pythonnet not found"
**A:** 重新运行 `setup.bat`，或手动执行 `pip install pythonnet`

### Q: 我的 Power BI 安装在其他盘
**A:** 不需要手动配置！`test_connection.py` 会自动检测并显示路径。

### Q: 修改 Measure 后 PBIX 中的星号消失了
**A:** 这是正常的。修改已直接保存到模型，不需要再手动保存。可以在 Power BI Desktop 中验证数据是否正确。

### Q: 能在 Mac 上用吗？
**A:** 不能。Power BI Desktop 的 SSAS 引擎只在 Windows 上运行。

---

## 技术信息

- **开发 & 测试：** Max Gu
- **联合开发：** Claude Code + Max Gu
- **版本：** 1.0.0 (2026-07)
- **许可：** MIT — 公司内部可自由使用和修改
- **依赖：** Python 3.11+, pythonnet, Power BI Desktop
- **安全：** 纯本地连接，数据不经过网络

---

## 文件说明

```
Claude-PowerBI-MCP/
├── setup.bat               ← 双击，一键部署全部
├── test_connection.py      ← 双击，测试连接
├── server.py               ← MCP 主程序（21 个工具）
├── ssas_client.py          ← 底层连接库
├── power_query.py          ← Power Query 读取模块
├── power_query_ssas.py     ← Power Query SSAS 读取
├── deploy.ps1              ← Claude 自动部署脚本
├── requirements.txt        ← Python 依赖
├── .mcp.json.template      ← 配置模板
├── .claude/
│   └── skills/
│       └── powerbi-model.md ← Skill 文件（自动触发）
├── docs/
│   ├── technical-whitepaper.md       ← 技术白皮书
│   ├── why-we-built-our-own-mcp.md   ← 通俗版说明
│   ├── project-proposal-v2.md        ← 立项计划
│   └── copilot-powerbi-mcp-implementation.md ← Copilot 参考
├── tests/                  ← 27 套测试记录
├── .gitignore
├── README.md               ← 中文文档
└── README_EN.md            ← 英文文档
```