Powerbi MCP

🚀 Power BI MCP Server

Power BI MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它允许 AI 助手通过自然语言与 Power BI 数据集进行交互。你可以直接在 AI 助手中对数据进行查询、生成 DAX 查询语句，并获取数据洞察，无需在不同工具间频繁切换，极大提升了数据交互的效率和便捷性。

🚀 快速开始

前提条件

• Python 3.8 或更高版本
• 支持 ADOMD.NET 的 Windows 系统，或者在 Linux 上使用 Docker（容器已包含运行时）
• SQL Server Management Studio (SSMS) 或 ADOMD.NET 客户端库（仅适用于 Windows）
• 启用了 XMLA 端点的 Power BI Pro/Premium 账户
• 具有访问 Power BI 数据集权限的 Azure AD 服务主体
• OpenAI API 密钥（自然语言功能可选）

安装步骤

1. 克隆仓库

git clone https://github.com/yourusername/powerbi-mcp-server.git
cd powerbi-mcp-server

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入你的凭证信息

4. 测试连接

python quickstart.py

与 Claude Desktop 集成配置

在以下配置文件中添加相关配置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "powerbi": {
      "command": "python",
      "args": ["C:/path/to/powerbi-mcp-server/src/server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/powerbi-mcp-server",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

使用 Docker

构建容器镜像：

docker build -t powerbi-mcp .

运行服务器：

docker run -it --rm -e OPENAI_API_KEY=<key> powerbi-mcp

容器默认监听 8000 端口。你可以通过环境变量或命令行参数覆盖主机和端口配置：

docker run -it --rm -e OPENAI_API_KEY=<key> -p 7000:7000 powerbi-mcp \
  python src/server.py --host 0.0.0.0 --port 7000

容器包含 pythonnet 和 pyadomd 所需的 .NET 运行时。它设置了 PYTHONNET_RUNTIME=coreclr 和 DOTNET_ROOT=/usr/share/dotnet，以便自动检测 .NET 运行时。环境变量与 .env.example 中的变量相对应，你可以使用 -e VAR=value 传递变量，或者在构建上下文中提供 .env 文件。

服务器在 /sse 端点提供 Server-Sent Events 服务。客户端应连接到此端点，然后将 JSON-RPC 消息 POST 到初始 endpoint 事件中提供的路径（通常为 /messages/）。

✨ 主要特性

• 🔗 直接连接 Power BI：通过 XMLA 端点连接到任何 Power BI 数据集。
• 💬 自然语言查询：使用简单的英语提问，即可获取 DAX 查询语句和结果。
• 📊 自动生成 DAX：借助 GPT-4o-mini 实现基于 AI 的 DAX 查询生成。
• 🔍 自动发现表格：自动探索表格、列和度量值。
• ⚡ 优化性能：采用异步操作和智能缓存机制。
• 🛡️ 安全认证：使用 Azure AD 进行服务主体认证。
• 📈 智能建议：根据你的数据提供相关问题建议。

🎥 实时演示

通过自然语言提问，从你的 Power BI 数据中获取即时洞察，彻底改变你的 Power BI 使用体验。

例如，你可以提问 "各地区的总销售额是多少？"，并立即从你的 Power BI 数据中获得洞察。

💻 使用示例

连接到数据集

Connect to Power BI dataset at powerbi://api.powerbi.com/v1.0/myorg/YourWorkspace

探索数据

What tables are available?
Show me the structure of the Sales table

提出问题

What are the total sales by product category?
Show me the trend of revenue over the last 12 months
Which store has the highest gross margin?

执行自定义 DAX

Execute DAX: EVALUATE SUMMARIZE(Sales, Product[Category], "Total", SUM(Sales[Amount]))

🔧 配置说明

所需凭证

1. Power BI XMLA 端点
   • 格式：powerbi://api.powerbi.com/v1.0/myorg/WorkspaceName
   • 在 Power BI 管理门户 → 工作区设置中启用。
2. Azure AD 服务主体
   • 在 Azure 门户 → 应用注册中创建。
   • 在 Power BI 工作区 → 访问设置中授予访问权限。
3. OpenAI API 密钥（可选）
   • 仅自然语言功能需要此密钥。
   • 如果未设置此密钥，依赖 GPT 模型的端点将被隐藏。
   • 从 OpenAI 平台 获取。
   • 使用的模型：gpt-4o-mini（比 GPT-4 便宜 200 倍）

环境变量

创建一个 .env 文件（OpenAI 设置可选）：

# OpenAI 配置（可选）
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini  # 默认使用 gpt-4o-mini

# 可选：默认 Power BI 凭证
# 当 `connect_powerbi` 操作未提供 tenant_id、client_id 或 client_secret 时，将使用这些值。
DEFAULT_TENANT_ID=your_tenant_id
DEFAULT_CLIENT_ID=your_client_id
DEFAULT_CLIENT_SECRET=your_client_secret

# 日志记录
LOG_LEVEL=INFO

🏗️ 架构说明

powerbi-mcp-server/
├── src/
│   └── server.py          # 主要的 MCP 服务器实现
├── docs/                  # 文档
├── examples/              # 示例查询和用例
├── tests/                 # 测试套件
├── .env.example          # 环境变量模板
├── requirements.txt      # Python 依赖项
├── quickstart.py        # 快速测试脚本
└── README.md           # 本文件

关键组件

1. PowerBIConnector：处理 XMLA 连接和 DAX 执行。
2. DataAnalyzer：基于 AI 实现查询生成和解释。
3. PowerBIMCPServer：实现 MCP 协议。

🔐 安全最佳实践

• 切勿提交凭证：使用 .env 文件，并将其添加到 .gitignore 中。
• 使用服务主体：避免使用个人凭证。
• 最小权限原则：仅授予数据集必要的访问权限。
• 定期轮换密钥：定期更新服务主体的密钥。
• 使用安全连接：始终使用 HTTPS/TLS。

🧪 测试

运行测试套件：

python -m pytest tests/

测试特定功能：

python tests/test_connection.py
python tests/test_dax_generation.py

🤝 贡献指南

我们欢迎你的贡献！详细信息请参阅 CONTRIBUTING.md。

1. 分叉仓库。
2. 创建你的功能分支 (git checkout -b feature/AmazingFeature)。
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')。
4. 将更改推送到分支 (git push origin feature/AmazingFeature)。
5. 打开一个拉取请求。

📊 性能指标

• 连接时间：2 - 3 秒
• 查询执行时间：根据复杂度不同，为 1 - 5 秒
• 令牌使用量：使用 GPT-4o-mini 时，每个查询约 500 - 2000 个令牌
• 成本：典型使用情况下，每天约 $0.02 - 0.06

🐛 故障排除

常见问题

1. 未找到 ADOMD.NET
   • 在 Windows 上，安装 SQL Server Management Studio (SSMS)。
   • 在 Linux 上，使用提供的 Docker 镜像，该镜像已包含跨平台的 ADOMD.NET 运行时。
2. 连接失败
   • 验证 Power BI 中是否启用了 XMLA 端点。
   • 检查服务主体是否具有工作区访问权限。
   • 确保数据集名称完全匹配。
3. 超时错误
   • 在 Claude Desktop 配置中增加超时时间。
   • 检查与 Power BI 的网络连接。

详细解决方案请参阅 TROUBLESHOOTING.md。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Anthropic 提供 MCP 规范。
• Microsoft 提供 Power BI 和 ADOMD.NET。
• OpenAI 提供 GPT 模型。
• MCP 社区提供灵感和支持。

📬 支持

• 📧 邮箱：sulaimanahmed013@gmail.com
• 💬 问题反馈：GitHub Issues
• 📚 完整文档：详细文档