FreelexHo/power-bi-mcp

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

Features

Authentication & Discovery

Dataset & Refresh Management

Diagnostics & Source Code

Query & Reporting

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

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:

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