# 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)](https://modelcontextprotocol.io) 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.

```mermaid
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+.

```bash
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:

```json
{
  "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`](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](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](LICENSE).