Power Bi Analyst Mcp

Power BI 分析师 MCP

让 Claude 分析你的 Power BI 数据。获取答案，而不是遭遇上下文窗口崩溃。

将 Claude（或任何 MCP 客户端）连接到你的 Power BI 语义模型。浏览表和度量值、运行 DAX 查询，并处理真实结果，即使数据集包含数万行也不例外。大型查询结果会自动保存到本地文件，并按需分页提供给 Agent，因此无论提取多少数据，你的 AI 会话都能保持快速、专注。

所有操作都在你的机器上运行。你的数据绝不会经过第三方中继。

---

可以实现的功能

分析工作的瓶颈从来不是真正的数据访问——Power BI 已经让人们能够访问数据。瓶颈在于解读：将数据转化为决策所需的专业且耗时的工作。此服务将这项解读工作交给大模型完成。

跨整个模型进行复合推理 人工分析师会先运行一个查询、阅读结果、形成假设，再运行另一个查询。这个过程串行进行，耗时数小时。Agent 可以连续运行 20 个查询——每个查询都基于上一个查询的结果——综合分析所有结果，并在几分钟内给出有理有据的结论。询问“是什么导致 EMEA 的利润率下降？”，Claude 就会探索度量值、深入分析各个市场、检查时间趋势、找出异常值并给出解释——无需你逐步指示。

人人都能用自然语言分析数据 任何利益相关方都可以提出数据问题，并得到由实时 DAX 支持的准确答案——无需了解 DAX，无需提交工单，也无需等待。过去需要经过培训的分析师才能完成的解读工作，现在可按需进行。

主动检测异常 按计划运行 Claude，检查关键度量值。它会查询数据、与之前的周期进行比较，并用通俗的语言标记超出预期范围的情况——让你无需打开仪表板，就能及时发现问题。

可自我说明的语义模型 “列出此数据集中的所有度量值，并说明各自的计算内容。”Claude 会探索架构并生成数据字典，适用于新员工入职、治理工作，以及任何想了解模型实际包含内容的人。

自动处理大型数据集 Power BI 查询可能返回数万行数据。若将所有数据直接返回，会占用大部分大模型上下文窗口，导致会话崩溃。此服务会将大型结果保存到本地 CSV，并向 Agent 提供简明摘要——行数、列名和 5 行预览——随后允许它按需分页读取文件。你可以获取完整数据集，同时保持 AI 会话精简。

不断积累的查询历史 每个成功的 DAX 查询都会记录在本地 JSONL 审计日志中——包括用户提出的问题、生成的 DAX、返回的列，以及 CSV 的保存位置。在后续会话中，Agent 会搜索此历史记录，查找相关的既有工作：可复用的 DAX 模式、先前计算的结果文件，以及早期分析中的上下文。用得越多，它就越快、越智能，而且你始终可以通过审计日志追溯每个数字的来源。

数据始终保留在你的设备上 查询、结果和令牌绝不会经过云中继。此服务在本地运行，通过与 Power BI Web 应用相同的 OAuth 设备代码流程进行身份验证，并将令牌存储在操作系统的原生安全存储中（Keychain / DPAPI / LibSecret）。

---

与 Microsoft 官方 MCP 服务的比较

Microsoft 为 Power BI 发布了两个 MCP 服务。此服务在用途和架构上都与它们不同。

	此服务	Microsoft Remote MCP	Microsoft Modeling MCP
用途	查询和分析现有模型	查询现有模型	构建和修改模型
运行位置	在你的设备本地运行	Microsoft 云基础设施	本地（Power BI Desktop）
数据路径	直接连接 Power BI REST API	经由 Microsoft MCP 中继	本地 XMLA
身份验证	OAuth 设备代码（委托）	通过远程服务进行 OAuth 身份验证	本地会话
大型结果	自动保存到本地 CSV	仅限上下文内	不适用
只读	是	是	否
适用对象	使用 Claude / Cursor 的分析师	使用 Copilot 的分析师	模型开发人员

---

使用效果

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%...

Agent 会探索架构、编写 DAX、处理文件并交付分析结果，全程无需操作 Power BI UI。

---

工具

工具	功能
authenticate	通过 OAuth 设备代码登录 — 返回一个 URL 和一次性代码；再次调用即可完成登录
logout	清除缓存的令牌（强制重新进行身份验证）
list_apps	列出你有权访问的所有 Power BI 应用 — 从这里开始；会返回每个应用对应的 workspaceId
list_datasets	列出工作区中的数据集／语义模型（使用 list_apps 返回的 workspaceId）
get_dataset_info	返回数据集元数据及最近 5 条刷新历史记录
list_tables	列出数据集中所有可见表
list_measures	列出度量值及其名称、表、说明和格式字符串
list_columns	列出列及其数据类型和键标志
execute_dax	运行 DAX 查询 — 小型结果以内联方式返回，大型结果保存为本地 CSV。传入 query_summary 可记录查询，以供日后参考。
read_query_result	分页读取大型 CSV 结果，无需将其全部加载到上下文中
search_query_history	按关键字、数据集或时间范围搜索本地查询日志 — 查找不同会话中的先前 DAX 查询及结果
delete_query_log_entry	删除一条查询日志（例如，发现所用方法有误时）

---

用户指南

前提条件

• Python 3.10+
• Power BI Pro、Premium Per User（PPU）或 Premium 容量许可证
• Azure AD 应用注册（免费，约需 5 分钟 — 见下文）

步骤 1 — 创建 Azure AD 应用注册

OAuth 2.0 需要一个客户端 ID，用于标识代表你执行操作的应用。注册免费，无需客户端密钥，且此处使用的两个只读范围无需 Power BI 管理员同意。

1. 前往 portal.azure.com → Azure Active Directory → 应用注册 → 新注册。

2. 为其命名（例如 PowerBI MCP）。在帐户类型中选择 仅此组织目录中的帐户（单租户）。点击 注册。

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

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

4. 仍在 身份验证 → 高级设置下，将 允许公共客户端流设为 是。保存。

5. 在 API 权限 → 添加权限 → Power BI Service 下，添加：

   • Dataset.Read.All
   • Workspace.Read.All

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

6. 在 概述页面复制以下两项，步骤 2 中会用到：

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

注意： 必须在 Power BI 管理门户（集成设置）中启用 Power BI 租户设置 “Dataset Execute Queries REST API”，execute_dax 才能正常工作。

---

步骤 2 — 安装并连接

此服务已发布到 PyPI。最快的运行方式是使用 uvx，无需手动安装或创建虚拟环境。

Claude Desktop

将以下内容添加到你的 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
• Windows：%APPDATA%\Claude\claude_desktop_config.json

几乎所有用户都必须设置 POWERBI_TENANT_ID。 大多数组织只有一个 Azure AD 租户。将其设为步骤 1 中的目录（租户）ID。如果保留为 organizations（默认值），身份验证将失败，或连接到错误的租户。

Cursor

在项目中添加 .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 install（替代方式）

pip install powerbi-analyst-mcp

然后将 uvx 命令块替换为：

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

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

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

bundle/ 中有两个清单文件：

文件	用途	Git
manifest.template.json	通用模板——通过 Claude 的界面在安装时提示用户输入凭据	已提交
manifest.json	组织专用——为静默部署硬编码凭据	被 Git 忽略——切勿提交

构建组织专用捆绑包：

# 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 分享给同事。他们只需将其拖放到 Claude Desktop → Settings → Developer。支持 macOS 和 Windows。

安全性： bundle/manifest.json 和 dist/ 均被 Git 忽略。只有不含凭据的模板会被提交。切勿将凭据添加到任何由 Git 跟踪的文件中。

---

典型分析工作流

连接后，让你的大模型按以下顺序自然地执行：

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=<workspaceId from app>   → returns dataset IDs
4. list_tables           workspace_id=<id>   dataset_id=<id>
5. list_measures         workspace_id=<id>   dataset_id=<id>   [table_name=<name>]
6. list_columns          workspace_id=<id>   dataset_id=<id>   [table_name=<name>]
7. search_query_history  [keyword="revenue"]  ← check if similar work exists from a prior session
8. execute_dax           workspace_id=<id>   dataset_id=<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=<savedTo>   [offset=0]   [limit=100]
                         ← page through large results without filling context

注意： 始终使用 list_apps（而非 list_workspaces）来查找工作区 ID。在由应用管理的组织中，数据集访问权限通过 Power BI 应用授予——使用 list_workspaces 返回的工作区 ID 可能会导致权限错误。

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
)

---

大型结果处理——详细说明

结果大小	处理方式
≤ 50 行	以 JSON 内联返回——无需额外操作
> 50 行	将完整结果保存到带时间戳的 CSV 文件；向 Agent 返回精简摘要

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

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

然后，Agent 可以使用 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 参数：

参数	类型	说明
query_summary	str（可选）	对用户请求的简短描述——会记录到本地查询历史中，以便审计并在不同会话之间复用。
result_name	str（可选）	用于 CSV 文件名的简短标签——例如，"gmv by market 2024" → dax_result_gmv_by_market_2024_20260305_143022.csv。最多 40 个字符。
max_rows	int（可选）	在 Power BI 引擎级别通过 TOPN 应用的硬性上限。无需改写 DAX，即可快速抽样。

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

---

限制

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

---

安全

• 令牌通过 msal-extensions 使用操作系统原生安全存储进行持久化：
  • macOS — Keychain
  • Windows — 由 DPAPI 加密的文件
  • Linux — LibSecret（gnome-keyring / KWallet）；如果不可用，则回退到加密文件
• 缓存文件写入 ~/.powerbi_mcp_token_cache.bin，并受 .gitignore 保护。
• 服务绝不会记录访问令牌。
• 所有数据访问均受用户自身 Power BI 权限控制（委派式 OAuth 2.0 — 无服务主体，无客户端密钥）。

---

贡献

请参阅 CONTRIBUTING.md，了解项目结构、开发环境设置、架构说明以及如何添加新工具。