powerbi-health-mcp

An AI-powered Power BI dataset health monitor, built with Claude + MCP.

This demo project connects Claude to a simulated Power BI tenant through the Model Context Protocol (MCP) and turns it into a dataset health analyst. Instead of clicking through refresh histories workspace by workspace, you ask:

"Run a health check on my Power BI tenant. What's broken, why, and what should I fix first?"

...and Claude calls the MCP tools, correlates refresh failures with gateway status, and answers with a prioritized action plan.

flowchart LR
    A[Claude Desktop] -- MCP (stdio) --> B[powerbi-health-mcp\nFastMCP server]
    B --> C[(Mock Power BI tenant\n3 workspaces, 7 datasets,\n2 gateways)]
    B -. same tool surface as .-> D[Power BI REST API]

Why mock data?

The point of the demo is the AI + MCP workflow, not tenant setup. The server ships with a realistic mock tenant (refresh histories are generated relative to now, so the demo always looks live) and requires zero credentials — clone and run. The tool surface intentionally mirrors the real Power BI REST API (groups, datasets, refreshes, gateways), so swapping the mock layer for requests calls with a service principal token is a contained change.

What's in the mock tenant

Dataset	Workspace	Seeded problem
Sales Master	Sales Analytics	none — healthy
Regional Pipeline	Sales Analytics	failing 3 days — expired SQL credentials
P&L Consolidated	Finance Reporting	refresh timeout at 120 min (no incremental refresh)
AP Aging	Finance Reporting	none — healthy
Budget vs Actuals FY24	Finance Reporting	stale 21 days — owner left the company
Plant Telemetry	Operations	failing — its gateway has been offline 30h
Logistics KPIs	Operations	intermittent failures — memory pressure on shared capacity

A good health-check answer should find all five problems, notice that Plant Telemetry's failures are a gateway issue rather than a dataset issue, and flag the orphaned owner on the stale dataset.

MCP tools exposed

Tool	Purpose
get_tenant_health_summary	One-shot overview: counts by health state, problem datasets, offline gateways
list_workspaces	Workspaces with capacity type
list_datasets	Datasets with owner, schedule, health state (optional workspace filter)
get_refresh_history	Per-dataset run history with durations and error messages
get_gateways	Gateway status + which datasets depend on each
trigger_refresh	Simulated on-demand refresh — fails again until the root cause is "fixed"

Health states: HEALTHY, DEGRADED (recent intermittent failures), FAILING (latest run failed), STALE (no successful refresh in 7+ days).

Setup

Requires Python 3.10+.

git clone https://github.com/<you>/powerbi-health-mcp.git
cd powerbi-health-mcp
pip install -r requirements.txt

# quick smoke test without any MCP client:
python server.py --selftest

Connect to Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "powerbi-health": {
      "command": "python",
      "args": ["/absolute/path/to/powerbi-health-mcp/server.py"]
    }
  }
}

A ready-to-edit copy is in claude_desktop_config.example.json.

Demo prompts to try

1. The health check — "Use the powerbi-health tools to run a full health check on the tenant. Group problems by root cause and give me a prioritized fix list."
2. Root-cause reasoning — "Plant Telemetry keeps failing. Is the problem the dataset or something upstream?" (Claude should correlate it with the offline gateway.)
3. The skeptic test — "Trigger a refresh of Regional Pipeline and tell me if that fixed it." (It won't — broken credentials — and Claude should say so instead of declaring victory.)
4. The report — "Write a Monday-morning status email to the BI team summarizing tenant health, with owners to contact for each issue."

Findings

My honest take on what worked and what didn't lives in FINDINGS.md — filled in after testing this with a real-world use case, as promised in the LinkedIn post that started this.

Roadmap

• [ ] Real Power BI REST API mode behind the same tool surface (service principal auth)
• [ ] execute_dax tool via the executeQueries endpoint
• [ ] Scheduled health snapshots + trend comparison ("what got worse this week?")

License

MIT — see LICENSE.