内容
# Power BI Desktop 本地 MCP 服务器
允许 AI 助手（例如 Claude Desktop、Cursor、Cline、Hermes 等）安全、动态地连接到本地运行的 **Power BI Desktop** 实例。
通过此服务器，LLM 可以发现打开的报表，检查表和列的架构（元数据），并执行自定义 DAX 查询以与数据交互或动态生成可视化。
## 使用以下提示为您的 AI 代理安装 MCP
在与 Cursor、Cline、Claude Desktop 或 Hermes 启动新会话时，复制并粘贴此提示，以使代理自动配置环境并了解工作流程：
```
1. **依赖项安装：** 如果 `.venv/` 目录不存在，请初始化 Python 虚拟环境 (`python -m venv .venv`)，激活它，并安装 `requirements.txt` 中声明的所有依赖项。
2. **技能注册：** 将 `.agents/skills/powerbi-pbir-editor` 自定义目录复制到您的本地全局技能目录（例如，在 Hermes 中：`C:\Users\{User}\AppData\Local\hermes\skills\`）。
3. **MCP 服务器注册：** 在您的全局配置文件中注册 `powerbi-local` MCP 服务器（例如，在 Hermes 中：`config.yaml`，在 Cursor/Cline 中：`mcpjson.json`）。
- **关键：** 配置指向本地虚拟环境（`.venv/Scripts/python.exe`）的 Python 可执行文件的命令和指向此存储库的 `launch.py` 脚本的参数。这可以防止导入 `mcp` 库时出现 sys.path 冲突（PYTHONPATH 污染）。
4. **了解您的能力（关键）：** 不要仅仅因为 MCP 工具没有可视化创建功能就假设您无法以编程方式创建报表页面或可视化。您具有完整的 filesystem 写访问权限。您应该通过在 `.Report/definition/pages/` 文件夹中创建目录和在 `visuals/` 子文件夹中编写 `visual.json` 文件来创建新的页面和可视化。根据 `powerbi-pbir-editor` 技能规则，从不告诉用户您无法创建可视化；您始终可以编写文件。
5. **下一步（来自人类的请求）：** 安装完成后，向人类提出以下下一步以继续：
- “我已成功安装和配置了 Power BI MCP 服务器和技能。”
- “请用您的项目打开 Power BI Desktop。”
- “为我提供您的 `.pbip` 文件的绝对路径和您要使用的表的名称，以便我可以开始建模和生成图表。”
```
## 主要功能
- **动态端口发现：** Power BI Desktop 启动了一个本地 SQL Server Analysis Services (SSAS) 实例，并为每个会话分配一个随机端口。此服务器自动扫描 Windows `AppData` 目录以识别活动的工作区会话并解析其本地端口。
- **通过 ADOMD.NET 进行稳健连接：** 该服务器利用 `pythonnet` 直接加载 Power BI Desktop 附带的原生 `Microsoft.PowerBI.AdomdClient.dll`，而不是依赖本地系统 OLE DB 提供程序（`MSOLAP`），后者经常出现架构不匹配（32 位与 64 位）或缺少驱动程序的问题。
- **架构检查：** 公开数据库架构，详细说明表、列、数据类型和可见性状态。
- **JSON 安全的 DAX 执行：** 执行复杂的 DAX 表达式（例如，`EVALUATE SUMMARIZECOLUMNS(...)`）并将原始 .NET 数据类型（小数、日期、空值）解析为干净的 JSON 可序列化结构。
- **自我净化环境：** 通过清除受污染的 `PYTHONPATH`/`PYTHONHOME` 环境变量并优先使用本地 `.venv` 目录来防止运行时依赖项导入问题（例如，`pywintypes` 或 `pythonnet` 冲突），自动将其环境与主机平台（例如 AI 代理运行器或全局 shell）隔离。
## 项目结构
- `pbi_connector.py`：利用 ADOMD.NET 客户端库和本地活动端口扫描的核心数据库连接器。
- `server.py`：使用高级 `FastMCP` 框架构建的 MCP 服务器的入口点。
- `requirements.txt`：Python 包依赖项。
- `launch.py`：用于在没有 PYTHONPATH 冲突的情况下运行服务器的净化包装器。
## 先决条件
1. **操作系统：** Windows（需要运行 Power BI Desktop 并加载原生 Windows .NET 程序集）。
2. **Python：** 版本 3.10 或更高。
3. **Power BI Desktop：** 已安装标准版（`C:\Program Files\Microsoft Power BI Desktop`）或 Microsoft Store 版。
## 安装和设置步骤
### 1. 克隆和设置工作区
导航到目录并运行：
```powershell
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境
.\.venv\Scripts\Activate.ps1
# 安装需求
pip install -r requirements.txt
```
### 2. 独立测试
打开包含已加载数据集的 Power BI Desktop：
```powershell
fastmcp run server.py
```
### 3. 在客户端（Cursor、Cline、Claude Desktop、Hermes）中注册 MCP 服务器
将以下块添加到您的 MCP 配置文件（例如，`C:\Users\{User}\AppData\Local\hermes\config.yaml` 或 `C:\Users\{User}\AppData\Roaming\Cursor\User\globalStorage\moe.etherelf.container\mcpjson.json`）：
```yaml
# yaml 格式（Hermes config.yaml）
mcp_servers:
powerbi-local:
command: C:/Users/{User}/powerbi-mcp/.venv/Scripts/python.exe
args:
- C:/Users/{User}/powerbi-mcp/launch.py
connect_timeout: 30
timeout: 120
```
```json
// json 格式（Cursor / Cline config）
{
"mcpServers": {
"powerbi-local": {
"command": "C:\\Users\\{User}\\powerbi-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\{User}\\powerbi-mcp\\launch.py"
]
}
}
}
```
## ⚠️ 人类和 AI 代理的黄金法则（PBIR 2.0.0+ / TMDL）
以编程方式创建或修改 Power BI 报表页面时，必须严格遵守这些规则。否则将导致 **空可视化占位符** 或 **报表损坏**。
### 1. 可视化的文件夹结构（PBIR 2.0.0+）
在现代 Power BI 项目中，可视化文件 **不得** 直接放在页面文件夹中。它们必须组织在 `visuals/` 子文件夹中，其中每个可视化都是一个包含 `visual.json` 文件的目录：
```
{proyecto}.Report/
definition/
pages/
{page-guid}/
page.json
visuals/
{visual-name}/
visual.json
```
### 2. 可视化 JSON 结构（visualContainer 架构）
投影和字段必须直接位于 `visual.query.queryState` 下（从不位于 `visual.json` 的根目录或 `visual` 下）。
示例可视化配置（`visual.json`）：
```json
{
"$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.5.0/schema.json",
"name": "treemap-servicio",
"position": { "x": 20, "y": 20, "z": 0, "width": 610, "height": 310, "tabOrder": 0 },
"visual": {
"visualType": "treemap",
"query": {
"queryState": {
"Group": {
"projections": [
{
"field": {
"Column": {
"Expression": { "SourceRef": { "Entity": "comidasrapidas" } },
"Property": "nse"
}
},
"queryRef": "comidasrapidas.nse",
"nativeQueryRef": "nse"
}
]
},
"Values": {
"projections": [
{
"field": {
"Measure": {
"Expression": { "SourceRef": { "Entity": "comidasrapidas" } },
"Property": "Promedio Servicio"
}
},
"queryRef": "comidasrapidas.Promedio Servicio",
"nativeQueryRef": "Promedio Servicio"
}
]
}
}
},
"drillFilterOtherVisuals": true,
"objects": {},
"visualContainerObjects": {
"title": [
{
"properties": {
"show": { "expr": { "Literal": { "Value": "true" } } },
"text": { "expr": { "Literal": { "Value": "'Servicio por NSE'" } } }
}
}
]
}
}
}
```
### 3. 列与度量规则（关键）
- **条形图/柱形图/折线图/漏斗图/饼图/环形图** 和 **树形图** **不允许** 在其 Y 轴/值轴上直接使用列（`"Column"`）。这样做将导致显示“选择或拖动字段”的警告的 **空可视化**。
- **解决方法：** 您必须首先在表的 `.tmdl` 文件中定义一个 DAX 度量（使用 MCP 工具 `add_measure_to_tmdl`），并在可视化 JSON 中将其引用为 `"Measure"` 投影。
- **表格可视化（`tableEx`）：** 直接列引用仅在表格可视化投影（`"Values"` 通道）中允许。
### 4. 按图表类型划分的投影键
- **条形图、柱形图、折线图、组合图、漏斗图、饼图、环形图：** 使用 `"Category"`（分组）和 `"Y"`（值/度量）。
- **树形图：** 使用 `"Group"`（分组）和 `"Values"`（度量/大小）。
- **表格（`tableEx`）：** 使用 `"Values"`（列投影数组）。
### 5. TMDL 度量格式
在追加度量到 TMDL 文件时：
- 如果格式字符串包含空格或符号，请用双引号括起 `formatString`（例如，`formatString: "0.00"` 或 `formatString: "$#,##0"`）。没有引号的字符串包含符号将导致 Power BI 崩溃。
- 通过在插入前扫描 TMDL 文件来防止重复度量。
- 编辑前始终关闭 Power BI Desktop（`taskkill /IM PBIDesktop.exe /F`）。
