Tabular Mcp

MCPBI - 表格模型 MCP 服务

这是一个用于本地运行的表格模型的模型上下文协议（MCP）服务，即在 Power BI Desktop 中运行的 PowerBI 模型。

此服务允许启用 MCP 的大模型客户端与您的表格模型通信，并帮助您调试、分析和编写 DAX 查询。

示例：Copilot 通过 MCP 查询表格模型

工作原理

它通过 ADOMD.NET 中的 AdomdConnection 连接到本地运行的表格模型实例。

基于此连接，服务可让客户端通过预定义工具执行 DAX 查询，并检索模型元数据（使用 DMV 查询），以确保高准确性；也可执行自定义 DAX 查询，用于调试和开发。

功能

配置选项

端口

指定要连接的 Power BI Desktop 实例端口（必填）。

# Example: Connect to Power BI Desktop instance on port 56751
dotnet run -- --port 56751

混淆

使用可配置的加密策略保护敏感数据：

• 无（默认）：不进行混淆
• 全部：屏蔽所有值
• 维度：仅屏蔽文本／日期字段（数值数据保持可见）
• 事实：仅屏蔽数值字段（保留维度上下文）

# Example: Protect customer/product names while keeping sales figures visible
dotnet run -- --port 56751 --obfuscation-strategy dimensions --encryption-key "YourSecureKey123!"

输出截断

自动限制行数，并提供全面的元数据：

• 默认限制为 500 行（可配置）
• 响应包含：totalRows、displayedRows、truncated、hasMore

# Example: Increase row limit for analysis
dotnet run -- --port 56751 --max-rows 2000

工具

list_objects

• 列出模型中的所有对象（表、列、度量值、关系）
• 返回对象类型、名称和基本元数据

get_object_details

• 获取特定对象（表、列、度量值）的详细元数据
• 返回属性、数据类型、关系和依赖项

list_functions

• 列出可用的 DAX 函数，可按类别或来源筛选
• 返回函数名称、说明、接口分类和来源

get_function_details

• 获取特定 DAX 函数的完整详细信息，包括完整的参数信息
• 返回函数签名、参数要求、返回类型和 DirectQuery 兼容性

run_query

• 对模型执行自定义 DAX 查询
• 返回包含元数据（总行数、是否截断）的查询结果

1. 模型探索

使用 [ListTables]、[GetTableColumns] 和 [GetTableRelationships]，无需在 Power BI Desktop 中手动逐项点击，即可快速了解陌生模型的结构。

2. DAX 辅助

大模型客户端可以使用 [ListMeasures] 和 [GetMeasureDetails] 了解您现有的 DAX 模式，并建议符合您命名惯例和计算风格的新度量值。

3. 调试

将 [RunQuery] 与 [ValidateDaxSyntax] 结合使用，即可迭代测试和改进 DAX 表达式，并立即获得语法和结果反馈。

validate_query

• 验证 DAX 查询语法，但不执行查询
• 返回语法是否正确，以及适用时的错误消息

analyze_query_performance

• 分析 DAX 查询性能并提供优化建议
• 返回执行时间、资源使用情况和改进建议

安装

设置说明

要求

• Power BI Desktop（打开 PBIX 文件以进行探索）
• Windows 操作系统
• Visual Studio Code（用于 MCP 服务集成）
• .NET 8.0 Runtime

从预构建版本安装

1. 下载版本：从 Releases 目录或 GitHub Releases 页面下载，并解压到你选择的位置。

2. 打开 Power BI Desktop，并加载你要操作的 PBIX 文件。

3. 获取 Power BI 实例信息

有几种方法可以检测 Power BI Desktop 实例。 最简单的方法是打开 Tabular Editor，查看连接字符串中的端口。

只需在下一步的 MCP 服务配置中添加端口（上例中为 63717）即可（可以忽略数据库 ID，因为此服务会连接到默认模型）。
如果你没有 Tabular Editor，可以使用随附的发现工具查找正在运行的实例和数据库。

打开 PowerShell，切换到版本目录，然后运行：

cd path\to\release
.\pbi-local-mcp.DiscoverCli.exe

注意：在 PowerShell 中，必须使用 .\ 前缀来运行当前目录中的可执行文件。

按照提示执行以下操作：

• 选择 Power BI Desktop 实例（通过端口识别）
• 选择要连接的数据库/模型

这会在版本目录中创建一个包含 PBI_PORT 和 PBI_DB_ID 的 .env 文件，你可以在 MCP 配置中引用该文件；如果直接指定端口，也可以忽略此文件。

4. 在编辑器中配置 MCP 服务。对于使用 Roo 的 VS Code，请创建/编辑 .roo/mcp.json：

   {
     "mcpServers": {
       "MCPBI": {
         "type": "stdio",
         "command": "path\\to\\release\\mcpbi.exe",
         "cwd": "path\\to\\release",
         "args": ["--port", "YOUR_PBI_PORT"],
         "disabled": false,
         "alwaysAllow": [
           "ListTables",
           "GetTableDetails",
           "GetTableColumns",
           "GetTableRelationships",
           "ListMeasures",
           "GetMeasureDetails",
           "PreviewTableData",
           "RunQuery",
           "ValidateDaxSyntax",
           "AnalyzeQueryPerformance",
           "ListFunctions",
           "GetFunctionDetails"
         ]
       }
     }
   }
   

   将 path\\to\\release 替换为实际的版本目录路径，并将 YOUR_PBI_PORT 替换为 PBI 实例的端口号。

从源代码安装（用于开发）

1. 克隆仓库：

   git clone <repository-url>
   cd MCPBI
   

2. 构建项目：

   dotnet build
   

3. 打开 Power BI Desktop，并加载 PBIX 文件。

4. 运行发现工具以创建 .env 文件：

   dotnet run --project pbi-local-mcp/pbi-local-mcp.csproj discover-pbi
   

   按照提示选择实例和数据库。

5. 在 .roo/mcp.json 中配置 MCP 服务：

   {
     "mcpServers": {
       "mcpbi-dev": {
         "type": "stdio",
         "command": "dotnet",
         "cwd": "path\\to\\MCPBI",
         "envFile": "path\\to\\MCPBI\\.env",
         "args": [
           "exec",
           "path\\to\\MCPBI\\pbi-local-mcp\\bin\\Debug\\net8.0\\pbi-local-mcp.dll"
         ],
         "disabled": false,
         "alwaysAllow": [
           "ListTables",
           "GetTableDetails",
           "GetTableColumns",
           "GetTableRelationships",
           "ListMeasures",
           "GetMeasureDetails",
           "PreviewTableData",
           "RunQuery",
           "ValidateDaxSyntax",
           "AnalyzeQueryPerformance",
           "ListFunctions",
           "GetFunctionDetails"
         ]
       }
     }
   }
   

   将 path\\to\\MCPBI 替换为实际的仓库路径。

配置说明

• 使用端口或 envFile：你可以在 args 中直接指定 Power BI 端口，也可以使用 envFile 从 .env 加载。
• 端口参数：发布版本配置中的 --port 参数会连接到该端口对应的 Power BI Desktop 实例。
• envFile：开发环境配置使用 envFile 自动从 .env 加载 PBI_PORT 和 PBI_DB_ID。
• alwaysAllow：列出无需用户逐次批准即可使用的所有工具。
• 工作目录：cwd 参数用于设置 .env 文件所在的工作目录。