✨ Power BI 建模 MCP 服务器

Power BI 建模 MCP 服务器 实现了 MCP 规范，在 AI 代理与 Power BI 语义模型之间建立无缝连接。该项目目前处于公开预览阶段，正式发布前其实施细节可能会发生重大变化。

通过 本地 MCP 服务器，Power BI 建模 MCP 服务器 将 Power BI 语义建模能力引入您的 AI 代理中。这使得开发者和 AI 应用程序能够以全新的方式与 Power BI 模型交互，从使用自然语言执行建模变更，到实现自主的 AI 代理开发工作流。

💡 您可以做什么？

• 🔄 使用自然语言构建和修改语义模型 - 向您的 AI 助手说明需求，它将利用此 MCP 服务器创建、更新和管理表、列、度量值、关系等，适用于 Power BI Desktop 和 Fabric 语义模型。

• ⚡ 大规模批量操作 - AI 应用程序可以同时对数百个对象执行批量建模操作——批量重命名、批量重构、模型翻译或模型安全规则——并提供事务支持和错误处理，从而将耗时数小时的重复性工作缩短至几秒钟。

• ✅ 应用建模最佳实践 - 轻松评估并针对您的模型实施建模最佳实践。

• 🤖 代理式开发工作流 - 支持处理 TMDL 和 Power BI 项目文件，使 AI 代理能够自主规划、创建和执行跨语义模型代码库的复杂建模任务。

• 🔍 查询和验证 DAX - AI 助手可以针对您的模型执行并验证 DAX 查询，帮助您测试度量值、排查计算问题以及探索数据。

📹 观看视频以获取端到端演示。

[!警告]

• 将 AI 代理连接到语义模型时需谨慎。底层的 LLM 可能会产生意外或不准确的结果，从而导致非预期的更改。在执行任何操作之前，请务必备份您的模型。
• LLM 可能在日志或响应中无意间暴露语义模型中的敏感信息，包括数据或元数据。分享聊天会话时请务必小心。 请参阅数据隐私与 LLM 提供商。
• Power BI 建模 MCP 服务器 仅能执行建模操作，无法修改其他类型的 Power BI 元数据，例如报表页面或语义模型中的图表布局等元素。
• 您选择的 AI 模型将直接影响所接收响应的质量和相关性。为获得最佳效果，建议选择深度推理模型，如 GPT-5 或 Claude Sonnet 4.5。有关可用模型的更多详细信息，请参阅 GitHub Copilot AI 模型比较。

📦 安装

安装此 MCP 服务器最简单的方式是结合使用 Visual Studio Code 扩展 和 GitHub Copilot。不过，您也可以在任何其他 MCP 客户端中手动安装。

Visual Studio Code（推荐）

1. 安装 Visual Studio Code。

2. 安装 GitHub Copilot 和 GitHub Copilot Chat 扩展。

3. 安装 Power BI 建模 MCP Visual Studio Code 扩展。

   

4. 打开 GitHub Copilot chat，确认 powerbi-modeling-mcp 已启用并被选中。

   

[!注释] 如果您在可用工具列表中未看到 powerbi-modeling-mcp，请确保在 GitHub.com 的 Copilot 设置中启用了 Copilot 中的 MCP 服务器 选项。对于企业账户，此选项默认关闭，需由管理员启用。

手动安装

此 MCP 服务器也可配置于其他 IDE、CLI 和 MCP 客户端中。

Node Package Executor (NPX)（需要 Node.js）

将 JSON 配置添加到您的 MCP 客户端中。Node 将自动从 @microsoft/powerbi-modeling-mcp npm 包下载 MCP 服务器。

{
	"powerbi-modeling-mcp": {
			"type": "stdio",
			"command": "npx",
			"args": [
				"-y",
				"@microsoft/powerbi-modeling-mcp@latest",
				"--start"				
			]
		}	
}

手动下载

1. 使用以下 URL 下载所需版本的 VSIX 包：
   • 模板：https://marketplace.visualstudio.com/_apis/public/gallery/publishers/analysis-services/vsextensions/powerbi-modeling-mcp/[version]/vspackage?targetPlatform=[platform]
   • 示例（版本 0.1.9，平台 win32-x64）：https://marketplace.visualstudio.com/_apis/public/gallery/publishers/analysis-services/vsextensions/powerbi-modeling-mcp/0.1.9/vspackage?targetPlatform=win32-x64
2. 将下载的 .visx 文件重命名为 .zip。
3. 将内容解压到您选择的文件夹中，例如：C:\MCPServers\PowerBIModelingMCP。
4. 运行 \extension\server\powerbi-modeling-mcp.exe。
5. 从控制台复制 MCP JSON 注册信息，并将其注册到您首选的 MCP 客户端工具中。

以下是一个应在大多数 MCP 客户端中适用的配置示例：

{
	"powerbi-modeling-mcp": {
		"type": "stdio",
		"command": "C:\\MCPServers\\PowerBIModelingMCP\\extension\\server\\powerbi-modeling-mcp.exe",
		"args": [
			"--start"                
		],
		"env": {}			
	}	
}

🚀 开始使用

首先，您必须连接到 Power BI 语义模型，该模型可以位于 Power BI Desktop、Fabric 工作区或 Power BI 项目 (PBIP) 文件中。

• 对于 Power BI Desktop：

  连接到 Power BI Desktop 中的 '[文件名]'。
  

• 对于 Fabric 工作区中的语义模型：

  连接到 Fabric 工作区 '[工作区名称]' 中的语义模型 '[语义模型名称]'。
  

• 对于 Power BI 项目文件：

  打开 PBIP 文件夹 '[PBIP 定义/TMDL 文件夹路径]' 中的语义模型。
  

连接建立后，您可以使用自然语言让 AI 代理进行任何建模更改。要开始使用，可以尝试以下场景之一。

示例场景

场景	提示示例
分析命名规范并批量重命名。	分析我的模型的命名规范，并建议重命名以确保一致性。 分析‘Sales’表的命名规范，并将相同的模式应用到整个模型中。
为整个模型设置描述，用于文档记录。	为所有度量值、列和表添加描述，清晰说明其用途，并用简单易懂的语言解释DAX代码背后的逻辑。
翻译你的语义模型。	为我的模型生成法语翻译，包括表、列和度量值。
将度量值重构为计算组或自定义函数。	将度量值‘Sales Amount 12M Avg’和‘Sales Amount 6M Avg’重构为一个计算组，并新增24个月和3个月的变体。
重构查询以使用语义模型参数。	分析所有表的Power Query代码，识别数据源配置，并创建语义模型参数，以便轻松切换数据源位置。
对比多个模型中的DAX查询性能。	连接到语义模型‘V1’和‘V2’，并将以下DAX查询分别在两个模型上进行性能对比。[DAX查询]
记录你的语义模型	生成一个Markdown文档（.md），为Power BI语义模型提供完整、专业的文档。使用简单的Mermaid图表展示表之间的关系；为每个度量值记录DAX代码及业务逻辑描述，并采用易于理解的业务术语命名；记录行级筛选器；通过分析Power Query代码记录数据源信息。

[!TIP] 上述场景仅为示例。该MCP服务器为您的代理配备了适用于任何类型模型变更的建模工具，只需提供合适的提示和上下文，即可自动化几乎任何建模任务。

确认提示

本MCP服务器支持Elicitation MCP协议，要求用户对以下操作进行批准：

• 在首次对语义模型进行修改之前。
• 在首次针对语义模型执行查询之前。

[!TIP] 您可以通过使用--skipconfirmation选项来配置MCP，以跳过这些确认步骤。

🛠️ 可用工具

工具名称	功能
connection_operations	连接到 Power BI Desktop 或 Fabric 工作区
database_operations	管理语义模型——连接、创建、更新、列出数据库，导入/导出 TMDL 文件夹，部署到 Fabric
transaction_operations	控制数据库事务（开始、提交、回滚、获取状态）
model_operations	操作整个模型（获取、创建、更新、刷新、获取统计信息、重命名）
table_operations	管理表（创建、更新、删除、获取、列出、刷新、重命名）
column_operations	管理单个表列（创建、更新、删除、获取、列出、重命名）
measure_operations	管理单个 DAX 度量（创建、更新、删除、获取、列出、重命名、在表之间移动）
relationship_operations	处理表之间的关系（创建、更新、删除、启用/禁用、查找）
dax_query_operations	对模型执行、验证和生成 DAX 查询
trace_operations	对语义模型执行跟踪操作，以捕获和分析 Analysis Services 事件。
partition_operations	管理表分区（创建、更新、删除、刷新特定分区）
user_hierarchy_operations	使用用户定义的层次结构（创建、更新、删除级别、重新排序）
calculation_group_operations	管理计算组以及用于时间智能和其他计算的计算项
security_role_operations	配置安全角色和行级安全性 (RLS) 表权限
perspective_operations	管理视角及其成员（针对不同受众的模型筛选视图）
named_expression_operations	使用命名表达式和 Power Query 参数（创建、更新、删除、获取、列出、重命名）
function_operations	管理单个 DAX 用户自定义函数
culture_operations	管理多语言支持的文化设置（创建、更新、删除、获取有效文化名称）
object_translation_operations	处理不同文化和语言之间的模型对象翻译
calendar_operations	管理日历对象和时间智能列组
query_group_operations	组织和管理 Power Query 表达式的查询组

[!NOTE]

• 本项目目前处于公开预览阶段，在正式发布之前，工具可能会发生重大变化。
• 您可以请 AI 解释可用的工具，并展示如何使用它们的示例。例如：告诉我使用 powerbi-modeling-mcp 可以做哪些事情，并给出一些示例

▶️ 可用提示

此 MCP 服务器包含内置提示，可帮助您快速上手。在 Visual Studio Code 中，只需在聊天框中输入 / 命令，即可访问可用的 MCP 提示。

提示名称	功能
CreateDAXQuery	根据您的语义模型和自然语言问题创建 DAX 查询。附加 dax_query_instructions_and_examples 资源，为 LLM 提供 DAX 语言上下文。
RunDAXQueryWithMetrics	执行 DAX 查询，可选择清除缓存并仅返回执行指标。
AnalyzeDAXQuery	通过清除缓存后运行 DAX 查询，并查看执行指标来分析查询性能，以发现潜在问题。
ConnectToPowerBIDesktop	搜索与文件名匹配的 Power BI Desktop Analysis Services 实例并连接到该实例。
ConnectToFabric	连接到 Fabric 工作区中的语义模型。
ConnectToPBIP	从 Power BI 项目文件中的语义模型加载 TMDL 定义。附加 powerbi_project_instructions 资源，为 LLM 提供 Power BI 项目 (PBIP) 上下文。

[!NOTE] 部分提示还会附加资源，为 LLM 提供重要上下文。

⚙️ 设置

MCP 服务器支持多个命令行选项和环境变量：

命令行选项	默认值	描述
--start		启动 MCP 服务器；这是与 MCP 客户端注册服务器所必需的。
--readwrite	是	默认启用，在将编辑应用到语义模型之前会显示确认提示（每个数据库仅一次），从而允许写操作。
--readonly		安全模式，禁止对语义模型进行任何写操作。
--skipconfirmation		自动批准所有写操作，无需确认提示。仅当您确信要执行的操作并且已对语义模型进行了适当备份时，才应使用跳过确认模式。
--compatibility	PowerBI	默认情况下，它针对 Power BI 语义模型进行了优化。如果您希望将此 MCP 服务器用于 Analysis Services 数据库，请将设置更改为 Full。
--authmode	interactive	设置身份验证模式：serviceprincipal 或 interactive。

环境变量名称	默认值	描述
AZURE_CLIENT_ID		Microsoft Entra 服务主体的应用程序（客户端）ID。在使用 --authmode serviceprincipal 时必填。
AZURE_TENANT_ID		Microsoft Entra 租户（目录）ID。在使用 --authmode serviceprincipal 时必填。
AZURE_CLIENT_SECRET		服务主体的客户端密码。在使用基于密码的身份验证且 --authmode serviceprincipal 时必填。
AZURE_CLIENT_CERTIFICATE_PATH		服务主体的 PFX/PEM 证书文件路径。在使用基于证书的身份验证而非客户端密码且 --authmode serviceprincipal 时必填。
AZURE_CLIENT_CERTIFICATE_PASSWORD		如果证书受密码保护，则为证书文件的密码。仅在使用基于证书的身份验证且 --authmode serviceprincipal 时使用。
PBI_MODELING_MCP_ACCESS_TOKEN		配置后，MCP 服务器会在连接到 Fabric 工作区中的语义模型时使用指定的访问令牌，而不会提示进行身份验证。这在应用程序自行处理身份验证的情况下非常有用。

对于 Visual Studio Code，您可以在 用户设置 中设置命令行选项和环境变量：

打开 Visual Studio Code 的 用户设置，并搜索 @ext:Microsoft.powerbi-modeling-mcp。

对于手动安装，您可以通过 MCP 服务器注册 JSON 文件中的 args 属性配置命令行选项，并通过 env 属性设置环境变量：

{
"servers": {
		"powerbi-modeling-mcp": {
			"command": "[MCP 服务器文件夹路径]\\powerbi-modeling-mcp.exe",
			"args": [
				"--start"
                , "--skipconfirmation"
			],
			"env": {
				"PBI_MODELING_MCP_ACCESS_TOKEN": "[ACCESS_TOKEN]"
			},
			"type": "stdio"
		}
	}
}

💬 反馈与支持

• 请查看故障排除指南，以诊断并解决常见问题。
• 我们正在公开开发此项目。您的反馈对我们非常重要，将帮助我们塑造 Power BI Modeling MCP 服务器的未来。
  • 👉 在公共 GitHub 仓库中提交问题——我们非常期待您的意见！

注意事项与限制

• 此 MCP 服务器遵循与外部工具执行建模操作相同的规则和行为。有关更多信息，请参阅文档。

数据隐私与 LLM 提供商

MCP 服务器在本地运行，并使用您现有的凭据和权限连接到您的语义模型——它不会绕过任何 Power BI 安全控制措施。然而，MCP 服务器检索的数据（元数据、模式或查询结果）会被发送到 MCP 客户端（例如 VS Code），随后可能作为对话上下文的一部分转发给配置的 LLM 提供商。

简而言之：AI 辅助功能不会扩大数据访问范围，但可能会将已访问的数据传输给 LLM 提供商。 治理工作应侧重于贵组织的 AI 数据处理政策以及 LLM 提供商的服务条款，而不应仅仅依赖 Power BI 的安全控制措施。

如果您使用 GitHub Copilot，请参阅GitHub Copilot 模型托管文档，了解数据如何与外部 AI 模型提供商共享的详细信息。

安全性

您的凭据始终通过官方的 Azure Identity SDK 安全地处理——我们绝不会直接存储或管理令牌。

MCP 作为一种现象，非常新颖且处于技术前沿。与所有新技术标准一样，请务必进行安全审查，以确保任何与 MCP 服务器集成的系统都符合您所在系统应遵守的所有法规和标准。这不仅包括 Power BI 建模 MCP 服务器，还涵盖您选择实施的任何 MCP 客户端/代理，直至模型提供商。

您应当遵循 Microsoft 针对 MCP 服务器的安全指导，包括启用 Entra ID 身份验证、安全的令牌管理和网络隔离。有关详细信息，请参阅 Microsoft 安全文档。

权限与风险

MCP 客户端可以根据用户的 Fabric RBAC 权限调用操作。如果客户端处于自主运行状态或配置不当，可能会执行破坏性操作。在部署之前，您应当审查并应用最小权限的 RBAC 角色，并实施相应的保护措施。然而，某些保护措施（例如用于防止破坏性操作的标志）并未在 MCP 规范中标准化，可能并非所有客户端都支持。

数据收集

本软件可能会收集有关您及您使用本软件的信息，并将其发送至 Microsoft。Microsoft 可能会利用这些信息来提供服务并改进其产品和服务。此外，本软件中的一些功能可能使您和 Microsoft 能够从您的应用程序用户处收集数据。如果您使用这些功能，必须遵守适用法律，包括向您的应用程序用户提供适当的通知，并附上 Microsoft 的隐私声明。有关数据收集和使用的更多信息，请参阅帮助文档和我们的隐私声明。您使用本软件即表示您同意上述做法。

合规责任

此 MCP 服务器可能会被安装、使用，并与第三方客户端和服务共享数据，例如运行在 Microsoft 合规边界之外的第三方 LLM。您有责任确保任何集成均符合适用的组织、监管和合同要求。

第三方组件

此 MCP 服务器可能使用或依赖第三方组件。您有责任审查并遵守任何第三方组件的许可协议及安全状况。

出口管制

使用本软件必须遵守所有适用的出口法律法规，包括美国《出口管理条例》以及当地司法管辖区的相关要求。

无担保 / 责任限制

本软件按“原样”提供，不提供任何形式的明示或默示保证或条件。对于因使用、误用或错误配置本软件而导致的任何损害，Microsoft 概不负责。

行为准则

本项目已采纳 Microsoft 开源行为准则。如需更多信息，请参阅 行为准则常见问题解答 或发送电子邮件至 open@microsoft.com，提出任何其他问题或意见。

Power BI Modeling MCP 快速上手指南

Power BI Modeling MCP Server 是一个基于模型上下文协议（MCP）的本地服务，旨在让 AI 代理能够无缝连接并操作 Power BI 语义模型。通过自然语言指令，您可以自动化执行建模任务、批量重构、DAX 验证及最佳实践检查。

⚠️ 重要警告：在连接 AI 代理之前，务必备份您的模型。LLM 可能会产生意外结果导致数据变更，且存在敏感信息泄露风险。本工具仅支持建模操作（如表、列、度量值），不支持修改报表页面或布局。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• 操作系统：Windows, macOS 或 Linux。
• 核心依赖：
  • Node.js：如果您选择使用 npx 方式安装（推荐手动配置时使用）。
  • Visual Studio Code (VS Code)：推荐使用此编辑器以获得最佳体验。
• 账号与权限：
  • 有效的 Microsoft 账号，拥有访问目标 Power BI 语义模型、Fabric 工作区或 PBIP 项目的权限。
  • GitHub Copilot 订阅：需激活 GitHub Copilot 及 GitHub Copilot Chat 扩展。
  • 企业用户注意：如果是企业账户，管理员需在 GitHub 设置中启用 "MCP servers in Copilot" 选项。
• AI 模型建议：为获得最佳推理效果，建议选择深度推理模型（如 GPT-4o, Claude Sonnet 等）。

安装步骤

您可以根据需求选择 VS Code 扩展安装（最简单）或 手动配置安装。

方法一：Visual Studio Code 扩展（推荐）

这是最便捷的集成方式，适合直接在 VS Code 中通过 Copilot 聊天使用。

1. 安装基础软件： 下载并安装 Visual Studio Code。

2. 安装必要扩展： 在 VS Code 扩展市场搜索并安装以下插件：

   • GitHub Copilot
   • GitHub Copilot Chat
   • Power BI Modeling MCP (或直接访问 安装链接)

3. 验证安装：

   • 打开 GitHub Copilot Chat 面板。
   • 确认工具列表中已显示 powerbi-modeling-mcp 并被选中。
   • 若未显示：请前往 GitHub.com 设置，确保已启用 "MCP servers in Copilot"。

方法二：手动配置 (适用于其他 IDE 或 CLI)

如果您需要在非 VS Code 环境中使用，可通过 npx 或下载二进制文件进行配置。

选项 A：使用 NPX (需 Node.js)

将以下 JSON 配置添加到您的 MCP 客户端配置文件中。Node 将自动从 npm 拉取最新包。

{
	"powerbi-modeling-mcp": {
			"type": "stdio",
			"command": "npx",
			"args": [
				"-y",
				"@microsoft/powerbi-modeling-mcp@latest",
				"--start"				
			]
	}	
}

选项 B：手动下载二进制文件

1. 下载安装包： 根据版本和平台下载 .vsix 包（示例为 v0.1.9, win32-x64）： https://marketplace.visualstudio.com/_apis/public/gallery/publishers/analysis-services/vsextensions/powerbi-modeling-mcp/0.1.9/vspackage?targetPlatform=win32-x64

2. 解压文件：

   • 将下载的 .vsix 文件重命名为 .zip。
   • 解压内容到指定目录，例如：C:\MCPServers\PowerBIModelingMCP。

3. 注册配置： 运行 \extension\server\powerbi-modeling-mcp.exe 获取注册信息，或在 MCP 客户端中添加如下配置：

{
	"powerbi-modeling-mcp": {
		"type": "stdio",
		"command": "C:\\MCPServers\\PowerBIModelingMCP\\extension\\server\\powerbi-modeling-mcp.exe",
		"args": [
			"--start"                
		],
		"env": {}			
	}	
}

基本使用

安装完成后，您需要先连接到具体的 Power BI 语义模型，然后即可通过自然语言下达指令。

1. 建立连接

在 Copilot 聊天窗口中，根据您的模型位置输入以下任一指令：

• 连接 Power BI Desktop 文件：

  Connect to '[文件名]' in Power BI Desktop
  

  (请将 [文件名] 替换为实际打开的 .pbix 文件名)

• 连接 Fabric 工作区中的语义模型：

  Connect to semantic model '[语义模型名称]' in Fabric Workspace '[工作区名称]'
  

• 连接 Power BI Project (PBIP) 文件夹：

  Open semantic model from PBIP folder '[PBIP 中 definition/TMDL 文件夹的路径]'
  

2. 执行建模任务

连接成功后，直接使用自然语言描述您的需求。系统会在首次修改或查询前请求您的确认（除非使用了 --skipconfirmation 参数）。

常用场景示例：

• 批量重命名以统一规范：

  "Analyze my model's naming conventions and suggest renames to ensure consistency." （分析我的模型命名规范，并建议重命名以确保一致性。）

• 自动生成文档描述：

  "Add descriptions to all measures, columns, and tables to clearly explain their purpose and explain the logic behind the DAX code in simple, understandable terms." （为所有度量值、列和表添加描述，用简单易懂的语言解释其用途及背后的 DAX 逻辑。）

• 模型翻译：

  "Generate a French translation for my model including tables, columns and measures." （为我的模型生成法语翻译，包括表、列和度量值。）

• 重构度量值为计算组：

  "Refactor measures 'Sales Amount 12M Avg' and 'Sales Amount 6M Avg' into a calculation group and include new variants: 24M and 3M." （将度量值重构为计算组，并包含新的变体：24M 和 3M。）

• DAX 查询基准测试：

  "Connect to semantic model 'V1' and 'V2'. And benchmark the following DAX query against both models. [在此处粘贴 DAX 查询]"

提示：以上仅为示例。只要提供清晰的上下文和指令，该 MCP 服务器可协助您完成 virtually any modeling task（几乎任何建模任务）。