PowerBI MCP Server

A full-featured Model Context Protocol (MCP) server for integration with Microsoft Power BI via the Azure AD API.

🎯 Features

📖 READ Operations (7 tools):

• get_workspaces - Retrieve a list of all available workspaces

• get_datasets - Retrieve a list of datasets (with optional filtering by workspace)

• get_reports - Retrieve a list of reports (with optional filtering by workspace)

• get_dataset_tables - Retrieve the table structure of a dataset

• query_dataset - Execute DAX queries against a dataset

• refresh_dataset - Trigger a dataset refresh

• get_refresh_history - Retrieve dataset refresh history

🏗️ WORKSPACE Management (3 tools):

• create_workspace - Create new workspaces

• delete_workspace - Delete workspaces

• add_workspace_user - Add users with access permissions

📊 DATASET Management (3 tools):

• create_dataset - Create datasets with tables and schema

• delete_dataset - Delete datasets

• update_dataset - Update dataset configuration

🗃️ TABLE Management (3 tools):

• create_table - Create tables in datasets

• delete_table - Delete tables

• update_table - Modify table structure

📋 COLUMN Management (3 tools):

• add_column - Add columns with data types

• delete_column - Delete columns

• update_column - Change column properties

🧮 MEASURE Management (3 tools):

• create_measure - Create calculated measures (DAX)

• delete_measure - Delete measures

• update_measure - Update DAX expressions

📈 REPORT Management (3 tools):

• create_report - Create new reports

• delete_report - Delete reports

• clone_report - Clone reports

📥 DATA Import (2 tools):

• add_table_rows - Add data to tables

• clear_table_rows - Clear table data

🌐 GATEWAY Management (2 tools):

• get_gateways - Retrieve a list of gateways

• get_gateway_datasources - Retrieve gateway data sources

TOTAL: 28 full-featured MCP tools for complete PowerBI management!

Supported features:

• ✅ Full PowerBI management: from workspace creation to adding visualizations

• ✅ Authentication via Azure AD (Service Principal)

• ✅ Automatic token refresh

• ✅ Comprehensive error handling and logging

• ✅ CRUD operations for all core entities

• ✅ DAX query execution and calculated measures

• ✅ Data import and table management

• ✅ Gateway integration for external data sources

• ✅ Workspace and permissions management

📋 Requirements

• Node.js 18+

• TypeScript

• A registered application in Azure AD

• Permissions for the Power BI API

🚀 Installation

1. Clone and install dependencies

git clone <repository-url>
cd powerbi_mcp_server
npm install

2. Configure the Azure AD Application

1. Go to Azure Portal → App registrations

2. Create a new application or use an existing one

3. In the "API permissions" section, add:

   • Power BI Service permissions:

     • Dataset.Read.All

     • Dataset.ReadWrite.All

     • Report.Read.All

     • Workspace.Read.All

   • Microsoft Graph (optional):

     • User.Read

4. In the "Certificates & secrets" section, create a new client secret

5. Copy the Application (client) ID, Directory (tenant) ID, and client secret

3. Configure environment variables

Copy .env.example to .env and fill it in:

cp .env.example .env

Edit .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. Build the project

npm run build

🎮 Usage

Starting the server

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

Integration with Claude Desktop

Add the following to the Claude Desktop configuration file:

{
  "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"
      }
    }
  }
}

Use in MCP-compatible clients

After connecting, the following tools are available:

Retrieve workspaces

get_workspaces()

Retrieve datasets

get_datasets(workspace_id?: string)

Execute a DAX query

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

Create a new dataset with a table

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 data to a table

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

📊 Usage examples

Example 1: Retrieve all workspaces

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

Example 2: DAX query

// 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]
        ]
      }
    ]
  }
}

🔧 Development

Project structure

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

Development commands

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

🛡️ Security

• ✅ Secure token storage and automatic refresh

• ✅ Credentials or tokens are never logged

• ✅ Validation of all incoming parameters

• ✅ HTTPS for all API calls

• ✅ Error handling for all scenarios

📝 Logging

The server uses Winston for logging. The logging level is configured via the LOG_LEVEL environment variable:

• error - errors only

• warn - warnings and errors

• info - informational messages (default)

• debug - detailed debug information

❗ Troubleshooting

Issue: "Authentication failed"

Solution: Check the correctness of the Azure AD credentials and permissions

Issue: "Dataset not found"

Solution: Make sure the service principal has access to the workspace/dataset

Issue: "DAX query failed"

Solution: Check the DAX query syntax and access permissions for the dataset

Issue: "MCP connection failed"

Solution: Make sure the server is running correctly and is accessible via stdio

📖 Additional resources

• Model Context Protocol Specification

• Power BI REST API Documentation

• Azure AD Authentication Guide

• DAX Reference

📄 License

ISC License

🤝 Contributing

Pull requests and issue reports are welcome. Before making changes:

1. Make sure all tests pass

2. Follow the project's code style

3. Update the documentation if necessary

Created for the Model Context Protocol ecosystem 🚀