Power BI MCP Server 🚀

🎥 实时演示

通过自然语言提问来转换您的Power BI体验，并从数据中获得即时洞察。

这是一个模型上下文协议（MCP）服务器，它使AI助手能够通过自然语言与Power BI数据集进行交互。查询数据，生成DAX，并在不离开AI助手的情况下获取洞察。

✨ 特性

• 🔗 直接连接到Power BI - 通过XMLA端点连接到任何Power BI数据集
• 💬 自然语言查询 - 用普通英语提问，获取DAX查询和结果
• 📊 自动DAX生成 - 使用GPT-4o-mini生成AI驱动的DAX查询
• 🔍 表发现 - 自动探索表、列和度量
• ⚡ 优化性能 - 异步操作和智能缓存
• 🛡️ 安全认证 - 使用Azure AD的服务主体认证
• 📈 智能建议 - 根据您的数据提供相关问题建议

🎥 演示

提问如“按地区总销售额是多少？”并从您的Power BI数据中获得即时洞察。

🚀 快速开始

系统需求及平台兼容性

平台	Python	.NET 运行时	ADOMD.NET	状态
Windows	3.10+	✅ 内置	✅ 可用	✅ 全面支持
Linux	3.10+	✅ 可用	⚠️ 仅Docker	✅ Docker支持
macOS	3.10+	✅ 可用	❌ 不可用	❌ 不支持

注意：对于Linux系统，请使用Docker运行服务器，包括所有依赖项。

预备条件

• Python 3.10或更高版本（3.8+可能工作但未正式支持）
• Windows上的ADOMD.NET 或 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配置

添加到您的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容器不使用.env文件。为了安全起见，.env文件被排除在Docker构建上下文中。您必须通过docker run -e、Docker Compose或云平台提供环境变量。

构建容器镜像：

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

服务器在/sse处公开了一个Server-Sent Events端点。客户端应连接到此端点，然后向初始endpoint事件提供的路径（通常是/messages/）POST JSON-RPC消息。

容器包括pythonnet和pyadomd所需的.NET运行时。它设置PYTHONNET_RUNTIME=coreclr和DOTNET_ROOT=/usr/share/dotnet，以便自动检测.NET运行时。

重要：Docker容器不使用.env文件。出于安全原因，您的本地目录中的任何.env文件都将通过.dockerignore排除在Docker镜像之外。相反，通过以下方式提供环境变量：

• docker run -e VARIABLE=value
• Docker Compose环境变量
• 云平台环境变量注入

可用的环境变量与.env.example中的相同。

📖 使用

配置完成后，您可以通过Claude与您的Power BI数据进行交互：

连接到您的数据集

连接到Power BI数据集在powerbi://api.powerbi.com/v1.0/myorg/YourWorkspace

探索您的数据

有哪些可用的表？
显示销售表的结构

提问

按产品类别总销售额是多少？
展示过去12个月收入的趋势
哪个商店的毛利最高？

执行自定义DAX

执行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_connector.py
python tests/test_server_process.py

集成测试

与实际Power BI数据集的真实集成测试可用但默认禁用。这些测试会连接到实际的Power BI服务，并可能会消耗API配额。

启用集成测试：

1. 配置测试环境

   cp .env.example .env
   # 编辑.env文件并设置：
   ENABLE_INTEGRATION_TESTS=true
   

2. 设置测试数据集配置

   # 测试Power BI数据集配置
   TEST_XMLA_ENDPOINT=powerbi://api.powerbi.com/v1.0/myorg/YourTestWorkspace
   TEST_TENANT_ID=your_tenant_id
   TEST_CLIENT_ID=your_client_id
   TEST_CLIENT_SECRET=your_client_secret
   TEST_INITIAL_CATALOG=YourTestDatasetName
   
   # 可选：用于验证的预期测试数据
   TEST_EXPECTED_TABLE=Sales
   TEST_EXPECTED_COLUMN=Amount
   TEST_DAX_QUERY=EVALUATE TOPN(1, Sales)
   TEST_MIN_TABLES_COUNT=1
   

3. 运行集成测试

   # 带有安全检查的交互式运行器
   python run_integration_tests.py
   
   # 或直接使用pytest
   python -m pytest tests/test_integration.py -v
   
   # 带有自动确认（CI/CD）
   python run_integration_tests.py --yes
   

集成测试覆盖率：

• ✅ Power BI数据集连接
• ✅ 表发现和模式检索
• ✅ DAX查询执行
• ✅ 示例数据检索
• ✅ MCP工具接口测试
• ✅ 自然语言查询生成（使用OpenAI）
• ✅ AI驱动的建议（使用OpenAI）

⚠️ 警告：集成测试连接到真实的Power BI数据集，并可能会消耗：

• XMLA端点使用配额
• OpenAI API令牌
• 网络带宽

仅在专用测试环境中运行集成测试。

🤝 贡献

我们欢迎贡献！请参阅CONTRIBUTING.md了解详情。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开Pull Request

📊 性能

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

🧪 测试

运行测试

# 检查环境兼容性
python scripts/check_test_environment.py

# 运行单元测试
python -m pytest tests/ -k "not test_integration" -v

# 运行集成测试（需要配置.env）
python -m pytest tests/test_integration.py -v

测试环境需求

• Python 3.10+（推荐）
• requirements.txt中的所有依赖项
• 对于集成测试：有效的Power BI连接凭证

平台特定测试

• Windows：支持完整的测试套件
• Linux：仅支持单元测试（使用Docker进行集成测试）
• macOS：仅支持单元测试（有限支持）

🐛 故障排除

常见问题

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
• 📚 文档：完整文档