PowerBI MCP Server

Полнофункциональный Model Context Protocol (MCP) сервер для интеграции с Microsoft Power BI через Azure AD API.

🎯 Возможности

📖 READ Operations (7 tools):

• get_workspaces - Получение списка всех доступных workspace
• get_datasets - Получение списка datasets (с возможностью фильтрации по workspace)
• get_reports - Получение списка отчетов (с возможностью фильтрации по workspace)
• get_dataset_tables - Получение структуры таблиц dataset
• query_dataset - Выполнение DAX запросов к dataset
• refresh_dataset - Запуск обновления dataset
• get_refresh_history - Получение истории обновлений dataset

🏗️ WORKSPACE Management (3 tools):

• create_workspace - Создание новых workspace
• delete_workspace - Удаление workspace
• add_workspace_user - Добавление пользователей с правами доступа

📊 DATASET Management (3 tools):

• create_dataset - Создание datasets с таблицами и схемой
• delete_dataset - Удаление datasets
• update_dataset - Обновление конфигурации datasets

🗃️ TABLE Management (3 tools):

• create_table - Создание таблиц в datasets
• delete_table - Удаление таблиц
• update_table - Модификация структуры таблиц

📋 COLUMN Management (3 tools):

• add_column - Добавление колонок с типами данных
• delete_column - Удаление колонок
• update_column - Изменение свойств колонок

🧮 MEASURE Management (3 tools):

• create_measure - Создание вычисляемых мер (DAX)
• delete_measure - Удаление мер
• update_measure - Обновление DAX выражений

📈 REPORT Management (3 tools):

• create_report - Создание новых отчетов
• delete_report - Удаление отчетов
• clone_report - Клонирование отчетов

📥 DATA Import (2 tools):

• add_table_rows - Добавление данных в таблицы
• clear_table_rows - Очистка данных таблиц

🌐 GATEWAY Management (2 tools):

• get_gateways - Получение списка gateway
• get_gateway_datasources - Получение источников данных gateway

ИТОГО: 28 полнофункциональных MCP tools для полного управления PowerBI!

Поддерживаемые функции:

• ✅ Полное управление PowerBI: от создания workspace до добавления визуализаций
• ✅ Аутентификация через Azure AD (Service Principal)
• ✅ Автоматическое обновление токенов
• ✅ Comprehensive error handling и логирование
• ✅ CRUD операции для всех основных сущностей
• ✅ DAX query execution и вычисляемые меры
• ✅ Импорт данных и управление таблицами
• ✅ Gateway integration для внешних источников данных
• ✅ Workspace и permissions management

📋 Требования

• Node.js 18+
• TypeScript
• Зарегистрированное приложение в Azure AD
• Permissions для Power BI API

🚀 Установка

1. Клонирование и установка зависимостей

git clone <repository-url>
cd powerbi_mcp_server
npm install

2. Настройка Azure AD Application

1. Перейдите в Azure Portal → App registrations

2. Создайте новое приложение или используйте существующее

3. В разделе "API permissions" добавьте:

   • Power BI Service permissions:
     • Dataset.Read.All
     • Dataset.ReadWrite.All
     • Report.Read.All
     • Workspace.Read.All
   • Microsoft Graph (optional):
     • 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-совместимых клиентах

После подключения доступны следующие tools:

Получение 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 запуск

🛡️ Безопасность

• ✅ Secure token storage и автоматическое обновление
• ✅ Никогда не логируются credentials или токены
• ✅ Валидация всех входящих параметров
• ✅ HTTPS для всех API вызовов
• ✅ Error handling для всех сценариев

📝 Логирование

Сервер использует Winston для логирования. Уровень логирования настраивается через переменную LOG_LEVEL:

• error - только ошибки
• warn - предупреждения и ошибки
• info - информационные сообщения (по умолчанию)
• debug - подробная отладочная информация

❗ Troubleshooting

Проблема: "Authentication failed"

Решение: Проверьте правильность Azure AD credentials и permissions

Проблема: "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 🚀