Power BI Authoring MCP Server (Local)

✨ Power BI Authoring MCP 服务

重要

在 Fabric 工作区中创作语义模型时，请使用远程（托管）Power BI Authoring MCP 服务。它无需本地安装，更新由 Microsoft 管理。请参阅 Power BI Authoring MCP server，了解远程和本地选项的区别。

Power BI Authoring MCP Server 实现了 MCP 规范，可在 AI Agent 与 Power BI 语义模型之间建立无缝连接。

Power BI Authoring MCP Server 通过本地 MCP 服务，为 AI Agent 提供 Power BI 语义建模功能。开发者和 AI 应用可以借此采用全新的方式与 Power BI 模型交互，例如使用自然语言执行建模更改，或运行自主 AI Agent 开发工作流。

💡 可以做什么？

• 🔄 使用自然语言创建和修改语义模型 - 告诉 AI 助手你的需求，它就会使用此 MCP 服务，在 Power BI Desktop 和 Fabric 语义模型中创建、更新和管理表、列、度量值、关系等内容。

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

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

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

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

📹 观看端到端演示视频。

警告

• 将 AI Agent 连接到语义模型时请务必谨慎。底层大模型可能生成意料之外或不准确的结果，从而导致意外更改。执行任何操作前，请务必备份模型。
• 大模型可能会无意中在日志或响应中泄露语义模型中的敏感信息，包括数据或元数据。分享聊天会话时请务必谨慎。 请参阅数据隐私和大模型提供商。
• Power BI Authoring 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 Chat 扩展。

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

   

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

   

说明

如果在可用工具列表中看不到 powerbi-modeling-mcp，请确认 GitHub.com 上 Copilot 设置中的 MCP servers in Copilot 选项已启用。对于企业账户，此选项默认处于禁用状态，必须由管理员启用。

手动配置

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

Node 包执行器（NPX）（需要 Node.js）

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

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

接受 EULA

使用 npm 包之前，必须阅读并接受 Power BI Authoring MCP Server EULA。在接受之前，MCP 服务会阻止所有其他工具调用。

在交互式会话中，获得你的明确授权后，Agent 可以代你调用 accept_eula 工具。服务会将接受记录保存在你设备上的本地配置中，因此不会再次提示你。

对于无人值守执行，可通过命令行参数或环境变量接受 EULA：

• 将 --accepteula 添加到服务的 args 数组中。
• 在服务的环境中将 PBI_MODELING_MCP_ACCEPT_EULA 设为 true。

请仅在阅读并同意 EULA 后使用这些选项。

手动下载

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\PowerBIAuthoringMCP
4. 运行 \extension\server\powerbi-modeling-mcp.exe
5. 从控制台复制 MCP JSON 注册信息，并在你首选的 MCP 客户端工具中注册。

以下配置示例适用于大多数 MCP 客户端：

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

🚀 开始使用

首先，你必须连接到 Power BI 语义模型，该模型可以位于 Power BI Desktop、Fabric 工作区或 Power BI Project（PBIP）文件中。

• 对于 Power BI Desktop：

  连接到 Power BI Desktop 中的“[File Name]”
  

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

  连接到 Fabric 工作区“[Workspace Name]”中的语义模型“[Semantic Model Name]”
  

• 对于 Power BI Project 文件：

  从 PBIP 文件夹“[Path to the definition/ TMDL folder in the PBIP]”打开语义模型
  

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

示例场景

场景	提示词示例
分析命名规范并批量重命名。	Analyze my model’s naming conventions and suggest renames to ensure consistency. Analyze the naming convention of the ‘Sales’ table and apply the same pattern across the entire model.
为模型中的内容添加说明，便于编写文档。	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.
翻译语义模型。	Generate a French translation for my model including tables, columns and measures.
将度量值重构为计算组或 UDF。	Refactor measures 'Sales Amount 12M Avg' and 'Sales Amount 6M Avg' into a calculation group and include new variants: 24M and 3M.
重构查询以使用语义模型参数。	Analyze the Power Query code for all tables, identify the data source configuration, and create semantic model parameters to enable easy switching of the data source location.
对多个模型运行 DAX 查询基准测试。	Connect to semantic model 'V1' and 'V2. And benchmark the following DAX query against both models. [DAX Query]
编写语义模型文档	Generate a Markdown document (.md) that provides complete, professional documentation for a Power BI Semantic Model. Use a simple mermaid diagram to ilustrate the table relationships; Document each measure including the DAX code and a description of the business logic using business friendly names; Document row level filters; Document the data sources by analyzing the Power Query code.

提示

上述场景仅为示例。此 MCP 服务为你的 Agent 提供适用于任何类型模型变更的建模工具；只要搭配合适的提示词和上下文，你几乎可以自动化任何建模任务。

🛠️ 可用工具

工具名称	功能说明
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 表达式的查询组

说明

• 你可以询问 AI 有哪些可用工具，并查看如何使用这些工具的示例。例如：Tell me with some examples what I can do with the Power BI Authoring MCP server

▶️ 可用提示词

此 MCP 服务内置了提示词，可帮助你快速上手。在 Visual Studio Code 中，在聊天中输入 / 命令即可访问可用的 MCP 提示词。

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

说明

部分提示词还会附加资源，为大模型提供重要上下文。

⚙️ 设置

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

命令行选项	默认值	说明
--start		启动 MCP 服务；向 MCP 客户端注册服务时必须使用。
--readwrite	是	默认启用；对语义模型进行编辑前，需先确认才能执行写入操作（每个数据库确认一次）。
--readonly		安全模式，可防止对语义模型执行任何写入操作。
--compatibility	PowerBI	默认针对 Power BI 语义模型进行优化。若要将此 MCP 服务用于 Analysis Services 数据库，请将设置改为 Full。
--authmode	interactive	设置身份验证模式：serviceprincipal 或 interactive。
--accepteula		接受 EULA，以便在无人值守的情况下运行。
环境变量名称	默认值	描述
-----------------------------------	-------	---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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_ACCEPT_EULA	false	设置为 true，即可接受无人值守执行所需的 EULA。
PBI_MODELING_MCP_ALLOWED_CONNECTION_HOSTS		以逗号分隔的受信任自定义主机名列表，MCP 服务可使用这些主机名连接到 Analysis Services 或 Power BI XMLA。

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

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

对于手动安装，可以在 MCP 服务注册 JSON 中使用 args 属性配置命令行选项，并使用 env 属性设置环境变量：

{
"servers": {
		"powerbi-authoring-local": {
			"command": "[Path To MCP Server folder]\\powerbi-modeling-mcp.exe",
			"args": [
				"--start"                
				, "--authmode=interactive"				   				
			],
			"type": "stdio"
		}
	}
}

连接主机允许列表

若要连接到非 Power BI 终结点（例如 Azure Analysis Services 或 SQL Server Analysis Services），请将其主机名添加到 PBI_MODELING_MCP_ALLOWED_CONNECTION_HOSTS 环境变量中。多个主机名之间用逗号分隔：

{
  "env": {
    "PBI_MODELING_MCP_ALLOWED_CONNECTION_HOSTS": "xmla.contoso.example,another-xmla.contoso.example,sqlserver_01:8373"
  }
}

更改配置后，请重启 MCP 服务。

重要

仅添加组织信任且计划用作 Analysis Services 或 Power BI XMLA 终结点的主机。MCP 服务连接时会向这些主机发送访问令牌，因此，通过允许列表控制主机可保护凭据。请勿仅为绕过验证错误而添加主机名；请先确认该终结点的运营方。

💬 反馈与支持

• 查看故障排除指南，诊断并解决常见问题。
• 我们正在公开开发此项目。我们非常重视您的反馈，这将帮助我们规划 Power BI Authoring MCP 服务的未来发展。
  • 👉 欢迎在公开的 GitHub 仓库中提交问题，我们期待听到您的意见！

注意事项和限制

• 您必须拥有语义模型的写入权限。更多信息，请参阅语义模型权限。
• 此 MCP 服务遵循通过 External Tools 执行建模操作时相同的规则和行为。更多信息，请参阅文档。
• 没有专门用于阻止使用此 MCP 服务的租户管理员设置。此服务通过 XMLA 终结点连接到语义模型。若要阻止通过 MCP 服务访问，您必须禁用 XMLA 终结点。这也会阻止依赖 XMLA 连接的其他工具和应用程序。更多信息，请参阅通过 XMLA 终结点连接语义模型。

许可证

使用此软件须遵守 Power BI Authoring MCP Server EULA。使用 NPX 安装时，必须明确接受该协议才能使用 MCP 工具。请参阅接受 EULA，了解可用的接受方式。

数据隐私和大模型提供商

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

简而言之：AI 辅助不会扩大数据访问范围，但可能会将已访问的数据传输给大模型提供商。 管理工作应着重关注贵组织的 AI 数据处理政策和大模型提供商的服务条款，而不应只关注 Power BI 安全控制。

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

安全性

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

MCP 作为一种新兴技术，仍处于前沿阶段。与所有新技术标准一样，请考虑进行安全审查，确保任何与 MCP 服务集成的系统都符合其应遵守的所有法规和标准。这不仅包括 Power BI Authoring MCP Server，也包括您选择实施的任何 MCP 客户端／Agent，直至模型提供商。

您应遵循 Microsoft 针对 MCP 服务的安全指南，包括启用 Entra ID 身份验证、安全管理令牌以及隔离网络。详情请参阅 Microsoft 安全文档。

权限和风险

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

数据收集

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

合规责任

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

第三方组件

此 MCP 服务可能会使用或依赖第三方组件。 您有责任审查并遵守任何第三方组件的许可证要求，并评估其安全状况。

出口管制

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

无担保／责任限制

本软件按“原样”提供，不附带任何明示或暗示的担保或条件。Microsoft 对因使用、误用或错误配置本软件而产生的任何损害不承担责任。

行为准则

本项目已采用 Microsoft 开源行为准则。如需了解更多信息，请参阅行为准则常见问题，或发送电子邮件至 [email protected] 联系我们，提出其他问题或意见。