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.

Related MCP server: PowerBI Analyst MCP

What's in the mock tenant

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

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.