Powerbi Remote MCP Server

Power BI分析师MCP

   


请Claude分析您的Power BI数据。获取答案——而不是上下文窗口崩溃。

将Claude（或任何MCP客户端）连接到您的Power BI语义模型。探索表和度量值，运行DAX查询，并处理真实结果——即使是在包含数万行的数据集上。大型查询结果会自动保存到本地文件，并按需分页到代理，因此无论您提取多少数据，您的AI会话都会保持快速和专注。

一切都在你的机器上运行。您的数据永远不会通过第三方中继。

______________________________________________________________________

什么是可能的

分析的瓶颈从来不是数据访问——Power BI已经为人们提供了访问权限。瓶颈是翻译：将数据转化为决策的熟练、耗时的工作。此服务器将该翻译移动到LLM。

整个模型的复合推理 人类分析师运行一个查询，读取结果，形成假设，运行另一个查询。这部连续剧连载了好几个小时。一个代理可以按顺序运行20个查询——每个查询由最后一个查询通知——综合所有查询，并在几分钟内得出合理的结论。问“是什么导致了EMEA地区的利润率下降？”Claude将探索衡量标准，深入市场，检查时间趋势，隔离异常值，并解释它——而无需你指导每一步。

面向所有人的自然语言分析 任何利益相关者都可以提出数据问题，并获得实时DAX支持的真实答案，而无需知道DAX是什么，无需提交工单，也无需等待。翻译层过去需要训练有素的分析师按需运行。

主动异常检测 根据你的关键指标，按照时间表运行克劳德。它查询数据，与之前的时期进行比较，并用简单的英语标记任何超出预期范围的东西——在任何人打开仪表板发现问题之前。

自文档语义模型 “列出此数据集中的每个度量，并解释它的计算结果。”Claude探索了该模式并生成了一个数据字典，这对入职培训、治理以及任何试图理解模型实际包含内容的人都很有用。

大型数据集，自动处理 Power BI查询可以返回数万行。返回所有内联将占用LLM的大部分上下文窗口并使会话崩溃。此服务器将大型结果保存到本地CSV，并为代理提供一个简洁的摘要——行数、列名、5行预览——然后让它按需浏览文件。您将获得完整的数据集。AI会话保持精简。

查询随时间复合的历史记录 每个成功的DAX查询都会在本地记录在JSONL审计跟踪中——用户询问的内容、生成的DAX、返回的列以及CSV的保存位置。在下一个会话中，代理将搜索此历史记录以查找相关的先前工作：可重用的DAX模式、先前计算的结果文件以及早期分析的上下文。你使用它的次数越多，它就越快、越聪明——而且你总是有一个审计跟踪，知道每个数字的来源。

您的数据保留在您的计算机上 查询、结果和令牌永远不会通过云中继。服务器在本地运行，通过与Power BI web应用程序相同的OAuth设备代码流进行身份验证，并将令牌存储在操作系统的本机安全存储（Keychain/DPAPI/LibSecret）中。

______________________________________________________________________

它与微软的官方MCP服务器相比如何

微软为Power BI发布了两个MCP服务器。这个服务器在用途和架构上与两者都不同。

______________________________________________________________________

它看起来像什么

You: Analyse revenue by market and product category for Q1 2025

Claude: Let me explore the dataset first.
        [calls list_tables → list_measures → execute_dax]

        The query returned 73,840 rows — saved to:
        ~/powerbi_output/dax_result_revenue_q1_2025_20260313_091204.csv

        [pages through results with read_query_result]

        Summary: EMEA leads at 44% of total revenue. The top category
        is Premium Hardware in both EMEA and AMER. APAC shows the
        strongest quarter-over-quarter growth at +18%...

代理探索模式、写入DAX、处理文件并交付分析，而无需您触摸Power BI UI。

______________________________________________________________________

工具

______________________________________________________________________

用户指南

先决条件

• Python 3.10+
• Power BI Pro、高级每用户（PPU）或高级容量许可证
• Azure AD应用程序注册（免费，约5分钟——见下文）

步骤1--创建Azure AD应用程序注册

OAuth 2.0需要 客户端ID 以确定哪个应用程序代表您。注册是免费的，不需要客户端密码，也不需要Power BI管理员同意此处使用的两个只读范围。

1. 首选 portal.azure.com → Azure Active Directory → 应用注册 → 新注册.

1. 命名（例如。 PowerBI MCP).对于帐户类型，请选择 仅此组织目录中的帐户 （单租户）。点击 注册.

1. 在...之下 认证 → 平台配置，添加 移动和桌面应用程序 并勾选此重定向URI：

   https://login.microsoftonline.com/common/oauth2/nativeclient

1. 仍在进行中 认证 → 高级设置，set 允许公共客户端流 到 是。保存。

1. 在...之下 API权限 → 添加权限 → Power BI服务，添加：

- Dataset.Read.All - Workspace.Read.All

如果您的租户需要管理员同意，请请求管理员授予。

1. 从 概述 第页，复制这两个文件——您将在步骤2中需要它们：

- 应用程序（客户端）ID - 目录（租户）ID

注： Power BI租户设置 “数据集执行查询REST API” 必须在Power BI管理门户（集成设置）中启用 execute_dax 工作。

______________________________________________________________________

步骤2——安装并连接

服务器发布在PyPI上。最快的跑步方式是 uvx，不需要手动安装或虚拟环境。

克劳德桌面版

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "powerbi": {
      "command": "uvx",
      "args": ["powerbi-analyst-mcp"],
      "env": {
        "POWERBI_CLIENT_ID": "your-application-client-id",
        "POWERBI_TENANT_ID": "your-directory-tenant-id"
      }
    }
  }
}

配置文件位于：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

POWERBI_TENANT_ID 几乎所有用户都需要。 大多数组织只有一个Azure AD租户。将此设置为您的 目录（租户）ID 从步骤1开始。留下它作为 organizations （默认）将导致身份验证失败或针对错误的租户。

光标

添加a .cursor/mcp.json 项目中的文件（或使用全局配置）：

{
  "mcpServers": {
    "powerbi": {
      "command": "uvx",
      "args": ["powerbi-analyst-mcp"],
      "env": {
        "POWERBI_CLIENT_ID": "your-application-client-id",
        "POWERBI_TENANT_ID": "your-directory-tenant-id"
      }
    }
  }
}

pip安装（替代）

pip install powerbi-analyst-mcp

然后更换 uvx 命令块包含：

"command": "powerbi-analyst-mcp",
"args": []

Claude Desktop捆绑包（.mcpb）——用于组织范围内的分发

A. .mcpb （MCP Bundle）是Claude Desktop通过拖放安装的ZIP存档，无需手动编辑配置。捆绑包在第一次运行时自动安装所有Python依赖项；唯一的先决条件是Python 3.10+。

两个清单住在 bundle/:

构建一个组织包：

# 1. Create your org manifest (one-time setup)
cp bundle/manifest.template.json bundle/manifest.json

编辑 bundle/manifest.json 并设定你的价值观 mcp_config.env:

"env": {
  "POWERBI_CLIENT_ID": "your-application-client-id",
  "POWERBI_TENANT_ID": "your-directory-tenant-id",
  "POWERBI_OUTPUT_DIR": "/custom/output/path"
}

POWERBI_OUTPUT_DIR 是可选的--完全省略它以使用默认值 ~/powerbi_output.

# 2. Build the bundle
chmod +x bundle/build.sh
./bundle/build.sh
# → dist/miinto-powerbi-analyst.mcpb  (gitignored)

分发： 分享 dist/*.mcpb 与同事。他们把它拖放到上面 克劳德桌面版→ 设置→ 开发者。适用于macOS和Windows。

安全： bundle/manifest.json 和 dist/ 两者都被忽视了。仅提交无凭据模板。永远不要向git跟踪的任何文件添加凭据。

______________________________________________________________________

典型分析工作流程

连接后，要求您的LLM自然地遵循以下顺序：

1. authenticate          ← first run only; returns a URL + code to open in browser,
                           then call authenticate again to complete sign-in
2. list_apps             → returns installed apps, each with a workspaceId
3. list_datasets         workspace_id=   → returns dataset IDs
4. list_tables           workspace_id=   dataset_id=
5. list_measures         workspace_id=   dataset_id=   [table_name=]
6. list_columns          workspace_id=   dataset_id=   [table_name=]
7. search_query_history  [keyword="revenue"]  ← check if similar work exists from a prior session
8. execute_dax           workspace_id=   dataset_id=
                         dax_query="EVALUATE SUMMARIZECOLUMNS(...)"
                         [query_summary="Revenue by market and product for Q1 2025"]
                         [result_name="revenue by market q1"]  ← names the saved CSV
                         [max_rows=500]                        ← optional row cap for sampling
9. read_query_result     file_path=   [offset=0]   [limit=100]
                         ← page through large results without filling context

注： 总是使用 list_apps （不是 list_workspaces)以发现工作区ID。在应用程序管理的组织中，数据集访问是通过Power BI应用程序授予的——使用来自的工作区ID list_workspaces 可能会导致权限错误。

DAX查询示例

-- Total sales by year
EVALUATE
SUMMARIZECOLUMNS(
    'Date'[Year],
    "Total Sales", [Total Sales]
)
ORDER BY 'Date'[Year]

-- Top 10 customers by revenue
EVALUATE
TOPN(
    10,
    SUMMARIZECOLUMNS('Customer'[Name], "Revenue", [Revenue]),
    [Revenue], DESC
)

-- Filtered subset
EVALUATE
CALCULATETABLE(
    'Sales',
    'Date'[Year] = 2024
)

______________________________________________________________________

大结果处理——详细

返回的大型结果摘要包含：

• rowCount --写入的行总数
• columns --列名和类型
• preview --前5行
• savedTo --CSV文件的绝对路径

然后，代理可以使用以下命令浏览文件 read_query_result:

read_query_result(
    file_path = "/path/from/savedTo",
    offset    = 0,      # zero-based row offset
    limit     = 100     # rows per page (default 100)
)

退货 rows, totalRows, offset, limit，以及 hasMore.增量 offset 通过 limit 以获取下一页。

execute_dax 用于控制结果大小的参数：

输出目录 默认为 ~/powerbi_output.用覆盖 POWERBI_OUTPUT_DIR 在您的MCP客户的 env 块。CSV文件和查询历史日志不会自动清理——手动管理目录或添加保留策略。

______________________________________________________________________

局限性

• 只读。 不支持创建、修改和删除Power BI工件。
• execute_dax 限制：每次查询100000行或1000000个值（Power BI API硬上限）。
• 速率限制：每位用户每分钟120个DAX查询请求。
• list_tables, list_measures，以及 list_columns 使用DAX INFO.VIEW.* 这些函数需要启用XMLA读取访问的导入或DirectQuery模型。
• CSV文件写入者 execute_dax 不会自动清理。

______________________________________________________________________

安全

• 令牌通过操作系统本机安全存储进行持久化 msal-extensions:

- macOS --钥匙扣 - 视窗 --DPAPI加密文件 - Linux --LibSecret（侏儒钥匙圈/KWallet）；如果不可用，则回退到加密文件

• 缓存文件被写入 ~/.powerbi_mcp_token_cache.bin 并且被覆盖 .gitignore.
• 服务器从不记录访问令牌。
• 所有数据访问都由用户自己的Power BI权限（委派的OAuth 2.0——没有服务主体，没有客户端机密）控制。

______________________________________________________________________

贡献

看 贡献.md 关于项目结构、开发环境设置、架构说明以及如何添加新工具。