PBIXRay MCP 服务器

一个用于 PBIXRay 的 模型上下文协议 (MCP) 服务器。

此 MCP 服务器将 PBIXRay 的功能公开为工具和资源，供 LLM 客户端与 Power BI (.pbix) 文件交互。

功能

• [x] 加载和分析 PBIX 文件
• [x] 数据模型探索
  • [x] 列出模型中的表
  • [x] 检索模型元数据
  • [x] 检查模型大小
  • [x] 获取模型统计信息
  • [x] 获取全面的模型摘要
• [x] 查询语言访问
  • [x] 查看 Power Query (M) 代码
  • [x] 访问 M 参数
  • [x] 探索 DAX 计算表
  • [x] 查看 DAX 度量值
  • [x] 检查 DAX 计算列
• [x] 数据结构分析
  • [x] 检索架构信息
  • [x] 分析表关系
  • [x] 使用分页访问表内容

工具列表是可配置的，因此您可以选择要提供给 MCP 客户端的工具。 如果您不使用某些功能，或者不想公开敏感信息，这将非常有用。

工具

工具	类别	描述
load_pbix_file	核心	加载 Power BI (.pbix) 文件进行分析
get_tables	模型	列出模型中的所有表
get_metadata	模型	获取有关 Power BI 配置的元数据
get_power_query	查询	显示用于数据转换的所有 M/Power Query 代码
get_m_parameters	查询	显示所有 M 参数值
get_model_size	模型	获取模型大小（以字节为单位）
get_dax_tables	查询	查看 DAX 计算表
get_dax_measures	查询	访问 DAX 度量值，并按表或度量值名称进行筛选
get_dax_columns	查询	访问计算列 DAX 表达式，并提供筛选选项
get_schema	结构	获取有关数据模型架构和列类型的详细信息
get_relationships	结构	获取有关数据模型关系的详细信息
get_table_contents	数据	检索指定表的内容，并支持分页
get_statistics	模型	获取有关模型的统计信息，并提供可选的筛选
get_model_summary	模型	获取当前 Power BI 模型的全面摘要

用法

WSL (推荐)

将服务器配置添加到您的客户端配置文件。 例如，对于 Claude Desktop：

{
  "mcpServers": {
    "pbixray": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "source ~/dev/pbixray-mcp/venv/bin/activate && python ~/dev/pbixray-mcp/src/pbixray_server.py"
      ]
    }
  }
}

WSL 路径转换 (Claude Project 实例说明)

在 Windows 上的 Claude Desktop 中使用 WSL 中的 PBIXRay MCP 服务器时，您需要注意加载 PBIX 文件时的路径差异。 Windows 路径（如 C:\Users\name\file.pbix）无法在 WSL 中直接访问。 让您的 AI 助手知道如何通过添加以下内容在路径之间进行转换： “请注意，mcp 服务器在 wsl 中运行。Windows 路径（如 C:\Users\name\file.pbix）无法在 WSL 中直接访问。 相反，在引用文件时使用 WSL 路径： Windows: C:\Users\name\Downloads\file.pbix" WSL: /mnt/c/Users/name/Downloads/file.pbix" 到项目说明或类似内容。

命令行选项

服务器支持多个命令行选项：

• --disallow [tool_names]: 禁用特定工具以提高安全性
• --max-rows N: 设置返回的最大行数（默认值：100）
• --page-size N: 设置分页结果的默认页面大小（默认值：20）

可以根据需要在 config json 中添加命令行选项：

{
 "mcpServers": {
   "pbixray": {
     "command": "wsl.exe",
     "args": [
       "bash",
       "-c",
        "source ~/dev/pbixray-mcp/venv/bin/activate && python ~/dev/pbixray-mcp/src/pbixray_server.py --max-rows 100 --page-size 50 --disallow get_power_query"
      ],
      "env": {}
    }
  }
}

查询选项

工具支持用于筛选和分页的附加参数：

按名称筛选

get_dax_measures、get_dax_columns、get_schema 等工具支持按特定名称进行筛选：

# 获取特定表中的度量值
get_dax_measures(table_name="Sales")

# 获取特定度量值
get_dax_measures(table_name="Sales", measure_name="Total Sales")

大型表的分页

get_table_contents 工具支持分页以有效地处理大型表：

# 获取 Customer 表的第一页（每页默认 20 行）
get_table_contents(table_name="Customer")

# 获取第二页，每页 50 行
get_table_contents(table_name="Customer", page=2, page_size=50)

开发和测试

您可以安装 PBIXRay MCP 服务器：

pip install pbixray-mcp-server

开发安装

对于从事该项目的开发人员：

1. 克隆存储库：

   git clone https://github.com/username/pbixray-mcp.git
   cd pbixray-mcp
   

2. 以开发模式安装：

   pip install -e .
   

3. 如果从源代码安装，请创建一个虚拟环境并安装依赖项：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   pip install mcp pbixray numpy
   

使用示例文件进行测试

该存储库包含示例文件和测试脚本，可帮助您入门：

# 使用 demo/ 文件夹中的示例 AdventureWorks Sales.pbix 文件进行测试
python tests/test_with_sample.py

# 尝试交互式演示
python examples/demo.py

# 用于隔离测试特定功能
python test_pagination.py
python test_metadata_fix.py

测试脚本将帮助您了解如何使用 demo/ 目录中提供的示例 PBIX 文件与服务器进行交互。

开发模式

要在开发期间测试服务器，请使用 MCP Inspector：

# 首先激活您的环境
source venv/bin/activate

# 运行 MCP Inspector
mcp dev src/pbixray_server.py

这将启动一个交互式会话，您可以在其中调用工具并测试响应。

项目结构

pbixray-mcp/
├── README.md            - 此文件
├── INSTALLATION.md      - 详细的安装说明
├── src/                 - 源代码
│   ├── __init__.py
│   └── pbixray_server.py
├── tests/               - 测试脚本
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_server.py
│   └── test_with_sample.py
├── examples/            - 示例脚本和配置
│   ├── demo.py
│   └── config/
├── demo/                - 示例 PBIX 文件
│   ├── README.md
│   └── AdventureWorks Sales.pbix
└── docs/                - 附加文档
    └── ROADMAP.md

贡献

非常欢迎贡献！

鸣谢

• Hugoberry - 原始 PBIXRay 库
• rusiaaman - WCGW（此 MCP 完全由 Claude 使用 wcgw 编写）

许可证（claude 坚持添加这些）

MIT 许可证