convez.ai
MCP Server
FreelexHo

power-bi-mcp

FreelexHo/power-bi-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalação

$npx convez-ai FreelexHo/power-bi-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Power BI MCP Server

An MCP (Model Context Protocol) server that lets AI agents manage Power BI workspaces, datasets, and refreshes via natural language.

Features

Authentication & Discovery

ToolDescription
pbi_authAuthenticate via Azure AD device code flow (with token caching & auto-refresh)
pbi_list_workspacesList accessible workspaces (with optional name filter)
pbi_list_datasetsList datasets in a workspace

Dataset & Refresh Management

ToolDescription
pbi_dataset_infoAggregate dataset metadata + datasources + gateways + refresh schedule + impacted reports + PBIP locate (single call)
pbi_refresh_datasetTrigger an Enhanced refresh (supports table-level, polling, retry, timeout)
pbi_refresh_manageRefresh lifecycle: view history (status), get execution details (details), or cancel (cancel)

Diagnostics & Source Code

ToolDescription
pbi_diagnoseOne-shot diagnostic report for refresh failures — root cause classification, error catalog, next actions, PBIP source hints
pbi_locate_pbipLocate PBIP source code for a dataset (fuzzy folder match + optional table TMDL & M source extraction)

Query & Reporting

ToolDescription
pbi_execute_queryExecute DAX queries against a dataset (supports RLS impersonation)
pbi_scheduled_refresh_reportGenerate a daily scheduled-refresh status report across all datasets in a workspace (JSON or Markdown table)

Architecture

server.py            # Entry point — configures logging, runs MCP via stdio
app.py               # FastMCP instance with server instructions
config.py            # Configuration loader (config.json, defaults, constants)
auth.py              # Azure AD device code flow, token caching, HTTP helpers
diagnostics.py       # Refresh error classification, PBIP folder/table locator
error_catalog.py     # Error code catalog + regex patterns for failure classification
tools/               # MCP tool modules (auto-registered via __init__.py)
  ├── auth_tool.py   #   pbi_auth
  ├── workspace.py   #   pbi_list_workspaces, pbi_list_datasets
  ├── dataset.py     #   pbi_dataset_info
  ├── refresh.py     #   pbi_refresh_dataset, pbi_refresh_manage
  ├── diagnose.py    #   pbi_diagnose, pbi_locate_pbip
  ├── query.py       #   pbi_execute_query
  └── report.py      #   pbi_scheduled_refresh_report
setup.ps1            # Azure AD App Registration automation (PowerShell)
config.json          # User-specific config (gitignored)

Quick Start

1. Install dependencies

git clone https://github.com/FreelexHo/power-bi-mcp.git && cd power-bi-mcp
uv venv && uv sync
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e .

2. Register in your MCP client

Add to your MCP client configuration:

Cursor / Windsurf / Antigravity IDE (mcp.json):

{
  "mcpServers": {
    "power-bi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/power-bi-mcp", "server.py"],
      "transport": "stdio"
    }
  }
}

3. Authenticate (one-time)

Just use the MCP! On first use, the agent will call pbi_auth and show you a message like:

To sign in, visit https://microsoft.com/devicelogin
and enter the code XXXXXXXX
  1. Open the link in your browser
  2. Enter the code shown
  3. Sign in with your Microsoft work account
  4. Approve the permissions

That's it. Tokens are cached to ~/.powerbi-mcp/token.json and auto-refreshed — you won't need to do this again unless you revoke access.

Configuration

The server works out of the box with a built-in public client_id. Create a config.json in the project root to customize:

{
    "client_id": "<your-azure-ad-client-id>",
    "token_cache_dir": "~/.powerbi-mcp",
    "pbip_root": "C:/path/to/your/pbip-repo/data/power-bi-report"
}
KeyDefaultDescription
client_idBuilt-in public appAzure AD App Registration client ID
token_cache_dir~/.powerbi-mcpDirectory for cached OAuth tokens
pbip_root(none)Local PBIP repo root — enables pbi_locate_pbip and pbi_diagnose source-level hints

A setup.ps1 script is included to automate App Registration creation via Azure CLI. See Advanced Setup below.

Troubleshooting

AADSTS7000218: The request body must contain ... client_assertion

Your organization may block public client flows. Ask your Azure AD admin to either:

  • Allow public client flows on the app registration, or
  • Create a dedicated App Registration for your team (use setup.ps1)

AADSTS65001: The user or administrator has not consented

First-time users in a new Azure AD tenant need to consent to Power BI permissions. If your tenant requires admin consent:

  • Ask your admin to grant consent via Azure Portal -> App registrations -> API permissions -> "Grant admin consent"
  • Or use setup.ps1 to create your own App Registration where you are the owner

AADSTS50076: MFA required or AADSTS50079

Multi-factor authentication is required by your organization. The device code flow supports MFA — complete the MFA challenge in your browser when prompted.

Not authenticated. Call pbi_auth first.

Token has expired and could not be refreshed. The agent should automatically re-trigger pbi_auth. If it doesn't, ask the agent to call pbi_auth again.

Token keeps expiring

By default, tokens are cached at ~/.powerbi-mcp/token.json. Make sure:

  • The directory is writable
  • You are not running multiple instances that overwrite each other's tokens

Refresh details return 403

A 403 on pbi_refresh_manage action=details typically indicates insufficient permissions or the refresh record has expired.

Advanced Setup

For organizations that require their own App Registration:

Prerequisites

  • Azure CLI
  • Azure AD permissions to create App Registrations

Run setup

./setup.ps1

This creates an Azure AD App Registration with the correct configuration:

SettingValue
Sign-in audienceMulti-tenant (any Azure AD directory)
Public client flowsEnabled
Redirect URIhttps://login.microsoftonline.com/common/oauth2/nativeclient
API PermissionsPower BI Service: Dataset.ReadWrite.All, Workspace.Read.All (Delegated)

Tech Stack

  • Python ≥ 3.10
  • FastMCP (mcp[cli] ≥ 1.6.0) — MCP server framework, stdio transport
  • httpx ≥ 0.27.0 — HTTP client for Azure AD & Power BI REST API calls

License

MIT

Ver o original no GitHub

Relacionados