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
• 📚 完整文檔：詳細文檔