Powerbi MCP AI Connector


](https://mseep.ai/app/sulaiman013-powerbi-mcp)

Power BI MCP 服务器 🚀

  

🎥 实时演示

Power BI MCP Server Demo

*提升您的Power BI体验——用自然语言提问，即时从数据中获得洞察。*

一个模型上下文协议（MCP）服务器，使AI助手能够通过自然语言与Power BI数据集进行交互。您可以在不离开AI助手的情况下查询数据、生成DAX（数据分析表达式）并获取见解。

✨ 特点

• 🔗（此符号在中文中无直接对应翻译，通常表示链接或连接） 直接连接Power BI - 通过XMLA端点连接到任何Power BI数据集
• 💬 自然语言查询 - 用简单的英语提问，获取DAX查询及结果
• 📊 表格/数据图表 自动DAX生成 - 利用GPT-4o-mini实现AI驱动的DAX查询生成
• 🔍（放大镜图标，通常表示搜索、查看细节或调查） “Table Discovery”可以翻译为“表发现”或“表格发现”，具体取决于上下文和使用场景。在数据库或数据分析的语境中，通常指的是自动识别或查找数据库中的表或表格的过程 - 自动探索表、列和度量
• ⚡（闪电符号，无直接对应中文含义，可保持原样或根据上下文意译为“闪电”等） 优化性能 - 异步操作和智能缓存
• 🛡️ 代表“盾牌”的符号，在中文中可以翻译为“盾”或直接用该符号表示（如果语境允许）。所以，这个符号可以翻译为“盾”。 安全认证 - 使用 Azure AD 进行服务主体身份验证
• 📈 表情符号“📈”可以翻译为“上扬的折线图”或“上升趋势”。在中文语境中，它常用来表示某种数据、价格或情况正在上升或有上升的趋势。 智能建议 - 根据您的数据获取相关问题建议

🎥 演示

Power BI MCP Demo

*提出诸如“各地区总销售额是多少？”之类的问题，并立即从您的Power BI数据中获得洞察。*

🚀 快速入门

系统要求与平台兼容性

注对于Linux系统，使用Docker来运行包含所有依赖项的服务器。

先决条件

• Python 3.10 或更高版本（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

1. 安装依赖项

   pip install -r requirements.txt

1. 配置环境变量

   cp .env.example .env
   # Edit .env with your credentials

1. 测试连接

   python quickstart.py

使用Claude Desktop进行配置

在您的Claude桌面配置文件中添加：

Windows： %APPDATA%\Claude\claude_desktop_config.json macOS（发音为 /ˈmækOS/，中文常音译为“麦奥斯”或直接使用原名）： ~/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 -eDocker Compose，或者您的云平台。

构建容器镜像：

docker build -t powerbi-mcp .

运行服务器：

docker run -it --rm -e OPENAI_API_KEY= powerbi-mcp

该容器监听在端口上 8000 默认情况下。使用以下方法覆盖主机或端口： 环境变量或命令行参数：

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

服务器在（某个地址）暴露了一个用于服务器发送事件（Server-Sent Events）的端点 /sse客户应该 连接到此端点，然后将JSON-RPC消息POST到提供的路径 初始的 endpoint 事件（通常 /messages/)。

该容器包含了所需的.NET运行时环境 pythonnet 并且 pyadomd。 它设定/安装 PYTHONNET_RUNTIME=coreclr 并且 DOTNET_ROOT=/usr/share/dotnet 所以，那个 .NET 运行时会自动检测。

重要的Docker 容器确实 非（或“不是”） 使用 .env 文件。任何 .env 文件在你的（这里） 本地目录将从 Docker 镜像中排除 .dockerignore 出于安全原因。 相反，请使用以下方式提供环境变量：

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

可用的环境变量与（系统/环境中）的环境变量相匹配 .env.example。

📖 使用方法

配置完成后，您可以通过Claude与您的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管理员门户中启用 → 工作区设置

1. Azure AD 服务主体

- 在 Azure 门户中创建 → 应用注册 - 在Power BI工作区中授予访问权限 → 访问设置

1. OpenAI API密钥 *（可选）*

- 仅需用于自然语言功能 - 如果未设置此密钥，则依赖GPT模型的端点将被隐藏 - 从……获取 OpenAI 平台 - 所用模型： gpt-4o-mini （比GPT-4便宜200倍）

环境变量

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

# OpenAI Configuration (optional)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini  # Defaults to gpt-4o-mini

# Optional: Default Power BI Credentials
# These values are used when the `connect_powerbi` action does not supply
# tenant_id, client_id or client_secret.
DEFAULT_TENANT_ID=your_tenant_id
DEFAULT_CLIENT_ID=your_client_id
DEFAULT_CLIENT_SECRET=your_client_secret

# Logging
LOG_LEVEL=INFO

🏗️ 建筑学

powerbi-mcp-server/
├── src/
│   └── server.py          # Main MCP server implementation
├── docs/                  # Documentation
├── examples/              # Example queries and use cases
├── tests/                 # Test suite
├── .env.example          # Environment variables template
├── requirements.txt      # Python dependencies
├── quickstart.py        # Quick test script
└── README.md           # This file

关键组件

1. PowerBI连接器 - 处理XMLA连接和DAX执行
2. 数据分析师 - 基于人工智能的查询生成与解释
3. PowerBIMCPServer（可译为“PowerBIM CPS服务器”或根据具体上下文简化为“BIM CPS服务器”，其中“CPS”可能代表某种特定的服务器或服务名称，具体翻译需结合上下文确定） - 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
   # Edit .env file and set:
   ENABLE_INTEGRATION_TESTS=true

1. 设置测试数据集配置

   # Test Power BI Dataset Configuration
   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

   # Optional: Expected test data for validation
   TEST_EXPECTED_TABLE=Sales
   TEST_EXPECTED_COLUMN=Amount
   TEST_DAX_QUERY=EVALUATE TOPN(1, Sales)
   TEST_MIN_TABLES_COUNT=1

1. 运行集成测试

   # Interactive runner with safety checks
   python run_integration_tests.py

   # Or directly with pytest
   python -m pytest tests/test_integration.py -v

   # Run with auto-confirmation (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. 提交一个拉取请求

📊 性能

• 连接时间2-3秒
• 查询执行根据复杂程度，1-5秒
• 代币使用使用GPT-4o-mini时，每个查询约500-2000个标记
• 成本典型使用情况下，每天约0.02-0.06美元

🧪 测试

运行测试

# Check environment compatibility
python scripts/check_test_environment.py

# Run unit tests
python -m pytest tests/ -k "not test_integration" -v

# Run integration tests (requires .env configuration)
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运行时

1. 连接失败

- 验证Power BI中是否已启用XMLA端点 - 检查服务主体是否具有工作区访问权限 - 确保数据集名称完全匹配

1. 超时错误

- 在Claude桌面配置中增加超时时间 - 检查与 Power BI 的网络连接

见 《TROUBLESHOOTING.md》翻译为中文是《故障排除指南.md》 以获取详细解决方案。

📝 许可证

这个项目采用MIT许可证授权——详见 许可证 详情请见文件。

🙏 致谢

• Anthropic（公司名，可译为“安萨提克”或根据官方中文名直接使用） 对于MCP规范
• 微软 适用于 Power BI 和 ADOMD.NET
• OpenAI（开放人工智能研究所） 对于GPT模型
• MCP社区，为灵感与支持而聚

📬 支持

• 📧 电子邮件：sulaimanahmed013@gmail.com
• 💬 问题：
• 📚 文档： 完整文档