PowerBI MCP Server

用于通过 Azure AD API 集成 Microsoft Power BI 的全功能 Model Context Protocol (MCP) 服务器。

🎯 功能特性

📖 READ 操作（7 个工具）：

• get_workspaces - 获取所有可用 workspace 的列表

• get_datasets - 获取 datasets 列表（支持按 workspace 过滤）

• get_reports - 获取报告列表（支持按 workspace 过滤）

• get_dataset_tables - 获取 dataset 的表结构

• query_dataset - 对 dataset 执行 DAX 查询

• refresh_dataset - 启动 dataset 刷新

• get_refresh_history - 获取 dataset 的刷新历史

🏗️ WORKSPACE 管理（3 个工具）：

• create_workspace - 创建新的 workspace

• delete_workspace - 删除 workspace

• add_workspace_user - 添加具有访问权限的用户

📊 DATASET 管理（3 个工具）：

• create_dataset - 创建包含表和架构的 datasets

• delete_dataset - 删除 datasets

• update_dataset - 更新 datasets 的配置

🗃️ TABLE 管理（3 个工具）：

• create_table - 在 datasets 中创建表

• delete_table - 删除表

• update_table - 修改表结构

📋 COLUMN 管理（3 个工具）：

• add_column - 添加带数据类型的列

• delete_column - 删除列

• update_column - 修改列属性

🧮 MEASURE 管理（3 个工具）：

• create_measure - 创建计算度量（DAX）

• delete_measure - 删除度量

• update_measure - 更新 DAX 表达式

📈 REPORT 管理（3 个工具）：

• create_report - 创建新报告

• delete_report - 删除报告

• clone_report - 克隆报告

📥 DATA 导入（2 个工具）：

• add_table_rows - 向表中添加数据

• clear_table_rows - 清空表数据

🌐 GATEWAY 管理（2 个工具）：

• get_gateways - 获取 gateway 列表

• get_gateway_datasources - 获取 gateway 的数据源

总计：28 个用于完全管理 PowerBI 的全功能 MCP 工具！

支持的功能：

• ✅ 完整的 PowerBI 管理：从创建 workspace 到添加可视化

• ✅ 通过 Azure AD 进行身份验证（Service Principal）

• ✅ 自动令牌刷新

• ✅ 全面的错误处理和日志记录

• ✅ 所有主要实体的 CRUD 操作

• ✅ DAX 查询执行和计算度量

• ✅ 数据导入和表管理

• ✅ 用于外部数据源的 Gateway 集成

• ✅ Workspace 和权限管理

📋 要求

• Node.js 18+

• TypeScript

• 在 Azure AD 中注册的应用程序

• Power BI API 的权限

🚀 安装

1. 克隆并安装依赖

git clone <repository-url>
cd powerbi_mcp_server
npm install

2. 配置 Azure AD 应用程序

1. 转到 Azure Portal → App registrations

2. 创建新应用程序或使用现有应用程序

3. 在 "API permissions" 部分添加：

   • Power BI Service 权限：

     • Dataset.Read.All

     • Dataset.ReadWrite.All

     • Report.Read.All

     • Workspace.Read.All

   • Microsoft Graph（可选）：

     • User.Read

4. 在 "Certificates & secrets" 部分创建新的 client secret

5. 复制 Application (client) ID、Directory (tenant) ID 和 client secret

3. 配置环境变量

将 .env.example 复制为 .env 并填写：

cp .env.example .env

编辑 .env：

# Azure AD Configuration
AZURE_CLIENT_ID=your_application_client_id
AZURE_CLIENT_SECRET=your_client_secret
AZURE_TENANT_ID=your_tenant_id

# PowerBI API Configuration  
POWERBI_API_URL=https://api.powerbi.com/v1.0/myorg

# Logging
LOG_LEVEL=info

4. 构建项目

npm run build

🎮 使用

启动服务器

npm start
# или для development:
npm run dev

与 Claude Desktop 集成

添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "powerbi": {
      "command": "node",
      "args": ["/path/to/powerbi_mcp_server/build/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "your_client_id",
        "AZURE_CLIENT_SECRET": "your_client_secret", 
        "AZURE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

在 MCP 兼容客户端中使用

连接后可使用以下工具：

获取 workspaces

get_workspaces()

获取 datasets

get_datasets(workspace_id?: string)

执行 DAX 查询

query_dataset(
  dataset_id: "your-dataset-id",
  dax_query: "EVALUATE VALUES('Table'[Column])",
  workspace_id?: "workspace-id"
)

创建带表的新 dataset

create_dataset(
  name: "Sales Dataset",
  tables: [{
    name: "Sales",
    columns: [
      { name: "Date", dataType: "Datetime" },
      { name: "Amount", dataType: "Double" },
      { name: "Product", dataType: "String" }
    ],
    measures: [{
      name: "Total Sales",
      expression: "SUM(Sales[Amount])",
      formatString: "Currency"
    }]
  }],
  workspace_id?: "workspace-id"
)

向表中添加数据

add_table_rows(
  dataset_id: "dataset-id",
  table_name: "Sales",
  rows: [
    ["2024-01-01", 1000, "Product A"],
    ["2024-01-02", 1500, "Product B"]
  ],
  workspace_id?: "workspace-id"
)

📊 使用示例

示例 1：获取所有 workspace

// Tool call: get_workspaces
// Response:
{
  "success": true,
  "data": [
    {
      "id": "workspace-guid",
      "name": "My Workspace", 
      "isReadOnly": false,
      "isOnDedicatedCapacity": true
    }
  ],
  "count": 1
}

示例 2：DAX 查询

// Tool call: query_dataset
{
  "dataset_id": "dataset-guid",
  "dax_query": "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)",
  "workspace_id": "workspace-guid"
}

// Response:
{
  "success": true,
  "data": {
    "tables": [
      {
        "rows": [
          ["Product A", 1000],
          ["Product B", 800]
        ]
      }
    ]
  }
}

🔧 开发

项目结构

src/
├── auth.ts          # Azure AD authentication
├── powerbi-client.ts # PowerBI REST API client  
├── server.ts        # MCP server implementation
├── types.ts         # TypeScript interfaces
├── logger.ts        # Logging configuration
└── index.ts         # Entry point

开发命令

npm run build    # Сборка TypeScript
npm run dev      # Development режим
npm start        # Production запуск

🛡️ 安全性

• ✅ 安全的令牌存储和自动刷新

• ✅ 绝不记录凭据或令牌

• ✅ 验证所有传入参数

• ✅ 所有 API 调用均使用 HTTPS

• ✅ 针对所有场景的错误处理

📝 日志记录

服务器使用 Winston 进行日志记录。日志级别通过 LOG_LEVEL 变量配置：

• error - 仅错误

• warn - 警告和错误

• info - 信息性消息（默认）

• debug - 详细的调试信息

❗ 故障排除

问题："Authentication failed"

解决方案： 检查 Azure AD 凭据和权限是否正确

问题："Dataset not found"

解决方案： 确保 service principal 有权访问 workspace/dataset

问题："DAX query failed"

解决方案： 检查 DAX 查询语法以及对 dataset 的访问权限

问题："MCP connection failed"

解决方案： 检查服务器是否正确启动并可通过 stdio 访问

📖 其他资源

• Model Context Protocol Specification

• Power BI REST API Documentation

• Azure AD Authentication Guide

• DAX Reference

📄 许可证

ISC License

🤝 为项目做贡献

欢迎提交 pull requests 和 issue reports。在做出更改之前：

1. 确保所有测试通过

2. 遵循项目的 code style

3. 如有必要，更新文档

为 Model Context Protocol ecosystem 而创建 🚀