PowerBI MCP Server

Servidor Model Context Protocol (MCP) totalmente funcional para la integración con Microsoft Power BI a través de Azure AD API.

🎯 Características

📖 Operaciones READ (7 herramientas):

• get_workspaces - Obtención de la lista de todos los workspaces disponibles

• get_datasets - Obtención de la lista de datasets (con posibilidad de filtrar por workspace)

• get_reports - Obtención de la lista de informes (con posibilidad de filtrar por workspace)

• get_dataset_tables - Obtención de la estructura de tablas del dataset

• query_dataset - Ejecución de consultas DAX al dataset

• refresh_dataset - Inicio de la actualización del dataset

• get_refresh_history - Obtención del historial de actualizaciones del dataset

🏗️ Gestión de WORKSPACE (3 herramientas):

• create_workspace - Creación de nuevos workspaces

• delete_workspace - Eliminación de workspaces

• add_workspace_user - Adición de usuarios con permisos de acceso

📊 Gestión de DATASET (3 herramientas):

• create_dataset - Creación de datasets con tablas y esquema

• delete_dataset - Eliminación de datasets

• update_dataset - Actualización de la configuración de datasets

🗃️ Gestión de TABLAS (3 herramientas):

• create_table - Creación de tablas en datasets

• delete_table - Eliminación de tablas

• update_table - Modificación de la estructura de tablas

📋 Gestión de COLUMNAS (3 herramientas):

• add_column - Adición de columnas con tipos de datos

• delete_column - Eliminación de columnas

• update_column - Cambio de propiedades de columnas

🧮 Gestión de MEDIDAS (3 herramientas):

• create_measure - Creación de medidas calculadas (DAX)

• delete_measure - Eliminación de medidas

• update_measure - Actualización de expresiones DAX

📈 Gestión de INFORMES (3 herramientas):

• create_report - Creación de nuevos informes

• delete_report - Eliminación de informes

• clone_report - Clonación de informes

📥 Importación de DATOS (2 herramientas):

• add_table_rows - Adición de datos a las tablas

• clear_table_rows - Limpieza de datos de las tablas

🌐 Gestión de GATEWAY (2 herramientas):

• get_gateways - Obtención de la lista de gateways

• get_gateway_datasources - Obtención de fuentes de datos del gateway

TOTAL: 28 herramientas MCP totalmente funcionales para la gestión completa de PowerBI.

Funciones compatibles:

• ✅ Gestión completa de PowerBI: desde la creación de workspaces hasta la adición de visualizaciones

• ✅ Autenticación a través de Azure AD (Service Principal)

• ✅ Actualización automática de tokens

• ✅ Manejo integral de errores y registro de logs

• ✅ Operaciones CRUD para todas las entidades principales

• ✅ Ejecución de consultas DAX y medidas calculadas

• ✅ Importación de datos y gestión de tablas

• ✅ Integración con Gateway para fuentes de datos externas

• ✅ Gestión de workspaces y permisos

📋 Requisitos

• Node.js 18+

• TypeScript

• Aplicación registrada en Azure AD

• Permisos para Power BI API

🚀 Instalación

1. Clonación e instalación de dependencias

git clone <repository-url>
cd powerbi_mcp_server
npm install

2. Configuración de la aplicación Azure AD

1. Vaya a Azure Portal → App registrations

2. Cree una nueva aplicación o use una existente

3. En la sección "API permissions" agregue:

   • Power BI Service permissions:

     • Dataset.Read.All

     • Dataset.ReadWrite.All

     • Report.Read.All

     • Workspace.Read.All

   • Microsoft Graph (opcional):

     • User.Read

4. En la sección "Certificates & secrets" cree un nuevo client secret

5. Copie el Application (client) ID, Directory (tenant) ID y el client secret

3. Configuración de variables de entorno

Copie .env.example a .env y complételo:

cp .env.example .env

Edite .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. Compilación del proyecto

npm run build

🎮 Uso

Inicio del servidor

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

Integración con Claude Desktop

Agregue al archivo de configuración de 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"
      }
    }
  }
}

Uso en clientes compatibles con MCP

Después de la conexión, están disponibles las siguientes herramientas:

Obtención de workspaces

get_workspaces()

Obtención de datasets

get_datasets(workspace_id?: string)

Ejecución de consulta DAX

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

Creación de un nuevo dataset con tabla

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"
)

Adición de datos a una tabla

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"
)

📊 Ejemplos de uso

Ejemplo 1: Obtención de todos los workspaces

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

Ejemplo 2: Consulta 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]
        ]
      }
    ]
  }
}

🔧 Desarrollo

Estructura del proyecto

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

Comandos de desarrollo

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

🛡️ Seguridad

• ✅ Almacenamiento seguro de tokens y actualización automática

• ✅ Nunca se registran credenciales ni tokens

• ✅ Validación de todos los parámetros entrantes

• ✅ HTTPS para todas las llamadas API

• ✅ Manejo de errores para todos los escenarios

📝 Registro de logs

El servidor usa Winston para el registro de logs. El nivel de registro se configura mediante la variable LOG_LEVEL:

• error - solo errores

• warn - advertencias y errores

• info - mensajes informativos (por defecto)

• debug - información de depuración detallada

❗ Solución de problemas

Problema: "Authentication failed"

Solución: Verifique la corrección de las credenciales y permisos de Azure AD

Problema: "Dataset not found"

Solución: Asegúrese de que el service principal tenga acceso al workspace/dataset

Problema: "DAX query failed"

Solución: Verifique la sintaxis de la consulta DAX y los permisos de acceso al dataset

Problema: "MCP connection failed"

Solución: Verifique que el servidor esté iniciado correctamente y sea accesible a través de stdio

📖 Recursos adicionales

• Model Context Protocol Specification

• Power BI REST API Documentation

• Azure AD Authentication Guide

• DAX Reference

📄 Licencia

Licencia ISC

🤝 Contribución al proyecto

Se aceptan pull requests e informes de issues. Antes de realizar cambios:

1. Asegúrese de que todas las pruebas pasen

2. Siga el code style del proyecto

3. Actualice la documentación si es necesario

Creado para el ecosistema Model Context Protocol 🚀