FreelexHo/power-bi-mcp

An MCP (Model Context Protocol) server that lets AI agents manage Power BI workspaces, datasets, and refreshes via natural language.
For refresh incidents, the server brings dataset context, execution errors, same-workspace report dependencies, and optional local PBIP source hints into one evidence bundle. An agent can use it to propose the next investigation step while leaving fixes and operational decisions to the operator.
Walk through a simulated refresh diagnosis, or follow Quick Start to connect your MCP client.
Features
Authentication & Discovery
| Tool | Description |
|---|---|
| pbi_auth | Authenticate via Azure AD device code flow (with token caching & auto-refresh) |
| pbi_list_workspaces | List accessible workspaces (with optional name filter) |
| pbi_list_datasets | List datasets in a workspace |
Dataset & Refresh Management
| Tool | Description |
|---|---|
| pbi_dataset_info | Aggregate dataset metadata + datasources + gateways + refresh schedule + impacted reports + PBIP locate (single call) |
| pbi_refresh_dataset | Trigger an Enhanced refresh (supports table-level, polling, retry, timeout) |
| pbi_refresh_manage | Refresh lifecycle: view history (status), get execution details (details), or cancel (cancel) |
Diagnostics & Source Code
| Tool | Description |
|---|---|
| pbi_diagnose | Collect refresh evidence, classify known errors, suggest next actions, and link matching local PBIP source |
| pbi_locate_pbip | Locate PBIP source code for a dataset (fuzzy folder match + optional table TMDL & M source extraction) |
Query & Reporting
| Tool | Description |
|---|---|
| pbi_execute_query | Execute DAX queries against a dataset (supports RLS impersonation) |
| pbi_scheduled_refresh_report | Generate a daily scheduled-refresh status report across all datasets in a workspace (JSON or Markdown table) |
Example: diagnose a failed dataset refresh
> **Simulated demonstration — not a real Power BI execution.** All names, IDs, paths, service responses, source code, and agent conclusions below are fictional. The example illustrates the current tool contract; it does not demonstrate a production incident, a successful repair, or measured time savings.
A failed refresh can leave several tables marked as failed. This workflow connects execution messages to a candidate table, matching local source, and reports that may still show stale data, giving the operator a concrete place to investigate.
1. Ask the agent
> In "Demo Operations", the "Demo Sales" dataset failed to refresh. Find the likely cause, show which reports in this workspace may be affected, and tell me what to inspect before retrying. Do not change settings or start a refresh.
For this example, assume:
- The MCP server is connected and authentication has completed through pbi_auth; the signed-in user can read the workspace, dataset, and refresh details.
- The dataset has a failed Enhanced API refresh with structured messages and objects.
- Optional source lookup is enabled through pbip_root, with a readable local file at /Demo Sales/Demo Sales.SemanticModel/definition/tables/fact_sales.tmdl.
2. Resolve the target, then diagnose
The agent discovers the workspace, then lists its datasets and uses the returned IDs. In this simulated discovery, "Demo Operations" maps to 11111111-1111-1111-1111-111111111111 and "Demo Sales" maps to 22222222-2222-2222-2222-222222222222.
Illustrative MCP tool names and arguments, called in order after reading each discovery result (these are not JSON-RPC envelopes):
The interface is pbi_diagnose(workspace_id: str, dataset_id: str, refresh_id: str = "") -> str. It returns a JSON-encoded string. With an empty refresh_id, it reads the latest **10** refresh records and selects the first record in API response order with status == "Failed" and refreshType == "ViaEnhancedApi". This may differ from the most recent scheduled or on-demand failure. To investigate a known incident, pass its requestId as refresh_id.