内容
# Power BI Desktop 本地 MCP 服务器
一款模型上下文协议（MCP）服务器，能够使 AI 助手（例如 Claude Desktop、Cursor、Cline 等）安全、动态地连接到本地运行的 **Power BI Desktop** 实例（仅限 Windows）。
通过此服务器，LLM 可以发现已打开的报表，检查表和列架构（元数据），并执行自定义 DAX 查询以与数据交互或动态生成可视化。
## 主要功能
- **动态端口发现：** Power BI Desktop 启动了一个本地 SQL Server Analysis Services（SSAS）实例，并为每个会话分配一个随机端口。此服务器会自动扫描 Windows `AppData` 目录以识别活动的工作区会话并解析其本地端口。
- **通过 ADOMD.NET 进行稳健连接：** 该服务器利用 `pythonnet` 直接加载 Power BI Desktop 附带的原生 `Microsoft.PowerBI.AdomdClient.dll`，避免依赖本地系统 OLE DB 提供程序（`MSOLAP`），后者经常因架构不匹配（32 位 vs. 64 位）或缺少驱动程序而出现问题。
- **架构检查：** 公开数据库架构，详细说明表、列、数据类型和可见性状态。
- **JSON 安全 DAX 执行：** 执行复杂的 DAX 表达式（例如 `EVALUATE SUMMARIZECOLUMNS(...)`）并将原始 .NET 数据类型（十进制、日期、空值）解析为干净的 JSON 可序列化结构。
- **自我净化环境：** 通过清除受污染的 `PYTHONPATH`/`PYTHONHOME` 环境变量并优先使用本地 `.venv` 目录来隔离其环境与宿主平台（例如 AI 代理运行器或全局 shell），从而防止运行时依赖导入问题（例如 `pywintypes` 或 `pythonnet` 冲突）。
## 项目结构
- `pbi_connector.py`：使用 ADOMD.NET 客户端库和本地活动端口扫描的核心数据库连接器。
- `server.py`：使用高级 `FastMCP` 框架构建的 MCP 服务器入口点。
- `requirements.txt`：Python 包依赖项。
- `create_dashboard.py`：演示如何运行 DAX 查询、在 `pandas` 中聚合数据并使用 `Plotly` 生成优质基于 Web 的仪表盘的配套脚本。
## 先决条件
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 文件，在终端中可以测试 MCP 服务器：
```powershell
fastmcp run server.py
```
## MCP 客户端注册
要在 AI 编辑器或聊天客户端（例如 Cursor、Cline 或 Claude Desktop）中使用此服务器，请在 MCP 配置文件中注册服务器。
### 配置文件 (`mcp_config.json` 或 `claude_desktop_config.json`)
将以下块追加到 `mcpServers` 对象中（确保替换路径为工作区的绝对路径）：
```json
{
"mcpServers": {
"powerbi-local": {
"command": "C:\\Path\\To\\Your\\powerbi-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Path\\To\\Your\\powerbi-mcp\\server.py"
]
}
}
}
```
## MCP 工具参考
服务器公开了以下工具：
1. **`list_instances`**
- *描述：* 检测并返回当前计算机上活动的本地 Power BI Desktop 实例。
- *返回：* 包含活动本地端口和临时目录路径的对象列表。
2. **`get_schema`**
- *参数：* `port`（字符串）
- *描述：* 连接到本地端口并返回语义模型表/列结构。
3. **`execute_dax`**
- *参数：* `port`（字符串），`query`（字符串）
- *描述：* 执行自定义 DAX 查询（例如 `EVALUATE 'Table'`）并返回格式化为 JSON 的行。
4. **`add_measure_to_tmdl`**
- *参数：* `tmdl_path`（字符串），`name`（字符串），`expression`（字符串），`format_string`（字符串，可选）
- *描述：* 直接将 DAX 度量标准追加到本地表 `.tmdl` 文件中。此操作确保度量标准永久保存在 Power BI 项目（PBIP）元数据中，而不仅仅存在于临时活动内存会话中。它会自动处理格式字符串的双引号以防止语法错误。
## 最佳实践与故障排除（PBIP / TMDL / PBIR）
在手动或基于代理的程序化编辑 Power BI 项目时，请遵循以下严格的开发规则以避免报告损坏和应用程序加载崩溃：
### 1. TMDL formatString 引号规则
在表格模型定义语言（TMDL）文件中，任何包含特殊字符、符号、运算符或空格的 `formatString` 属性（例如 `$`、`%`、`;`、`+` 或空格）**必须用双引号括起来**。
* **错误：** `formatString: $#,##0`（导致 Power BI Desktop 加载时崩溃）
* **正确：** `formatString: "$#,##0"` 或 `formatString: "+0.0%;-0.0%"`
* *注意：* `add_measure_to_tmdl` 工具会自动处理此问题。
### 2. 防范重复度量
在将 DAX 度量标准追加到 `.tmdl` 文件之前，请验证度量标准是否已定义（例如，在文件的开头来自先前的 `.pbix` 导出）。定义度量标准两次将触发致命的 TMDL 编译错误：“`No se pueden combinar objetos TMDL porque ambos declaran la misma propiedad: expression`”。
### 3. Git 集成和根路径权限错误
Power BI Desktop 自动检测目录树中的 Git 仓库以配置其项目设置。如果 `.git` 文件夹意外存在于根目录（例如 `C:\.git`），Power BI 将尝试在 `C:\.gitignore` 处写入 `.gitignore` 文件。由于非管理员用户无法写入 `C:\` 根目录，保存项目将崩溃并显示：“`Acceso denegado a la ruta de acceso 'C:\.gitignore'`”。
* **修复：** 删除意外的根级 `C:\.git` 文件夹。
### 4. 有效的 PBIR visualType 标识符
在注入自定义视觉布局到 `.Report\definition\pages\[page]\visuals\[visual]\visual.json` 时，仅使用官方 Power BI 内置 `visualType` 名称。使用无效名称会导致整个报告在启动时无法加载：
* **无效：** `columnClusteredChart`、`columnStackedChart`
* **有效的标准图表类型：**
- `"columnChart"`（处理集群列和堆积列布局）
- `"barChart"`（处理集群条形图和堆积条形图布局）
- `"lineChart"`、`"pieChart"`、`"donutChart"`、`"treemap"`、`"card"`、`"matrix"`、`"table"`、`"waterfallChart"`、`"areaChart"`、`"scatterChart"`
