# Power BI Unified MCP

One MCP interface for AI-driven Power BI semantic-model engineering and PBIR/PBIP report authoring.

Semantic-model operations are executed through Microsoft's Power BI Modeling MCP. This project adds unified orchestration, local PBIR/PBIP report authoring, safety controls, diagnostics, and stdio/HTTP transports behind a single MCP server.

Status: `Early Release / Public Preview - v0.2.0`

Power BI is a Microsoft product. This repository is not Microsoft-owned, it does not bundle Microsoft's modeling executable, and it is not a full replacement for Power BI Desktop.

## Why It Exists

Power BI automation currently spans two different layers:

- semantic-model engineering against Power BI Desktop or compatible tabular models
- PBIR/PBIP report definition editing on disk

This project brings those layers together so an AI client can inspect, validate, and modify reports and models through one MCP tool catalog while still honoring local safety controls.

## How It Is Different From Microsoft's Modeling MCP

Microsoft's Modeling MCP focuses on semantic-model operations such as connections, tables, columns, measures, relationships, DAX, roles, partitions, TMDL, and related metadata work.

`powerbi-unified-mcp` keeps that upstream capability, but adds:

- local PBIR/PBIP report project discovery and lifecycle
- page and visual authoring
- field binding and formatting
- themes, filters, interactions, validation, checkpoints, and undo
- one merged MCP surface for report and model work
- local policy enforcement, diagnostics, audit logging, and capability reporting

## Current Scope

What `v0.2.0` can do today:

- discover and open PBIR/PBIP report projects
- create, rename, duplicate, and delete report pages
- create, inspect, move, resize, retype, bind, and format supported visuals
- apply themes, set filters, configure visual interactions, and validate report structure
- create report checkpoints, restore checkpoints, and undo recent report changes
- proxy semantic-model operations from Microsoft's Modeling MCP
- support local Power BI Desktop discovery, connection, DAX validation/execution, and temporary measure CRUD through the upstream tool family
- expose stdio and HTTP transports using the official MCP SDK

What it does not yet do:

- direct live `.pbix` canvas mutation without a PBIR/PBIP project
- complete Power BI Service or Fabric lifecycle management
- bookmark mutation or full button/navigation authoring
- a complete conditional-formatting abstraction
- support for every native or custom Power BI visual
- hosted multi-user deployment, authentication, or RBAC as a finished product

## Architecture

```mermaid
flowchart TD
    A[AI Client / MCP Host] --> B[Power BI Unified MCP]

    B --> C[PBIR/PBIP Report Authoring Engine]
    B --> D[Microsoft Power BI Modeling MCP]

    C --> E[Pages]
    C --> F[Visuals]
    C --> G[Field Bindings]
    C --> H[Formatting]
    C --> I[Themes]
    C --> J[Filters & Interactions]
    C --> K[Validation & Checkpoints]

    D --> L[Power BI Desktop / Fabric Semantic Model]

    L --> M[Tables & Columns]
    L --> N[Measures & DAX]
    L --> O[Relationships]
    L --> P[Partitions]
    L --> Q[RLS / Security Roles]
    L --> R[Calculation Groups]
    L --> S[TMDL / TMSL]
```

Plain-language split:

- Report authoring is implemented in this repository and works on PBIR/PBIP projects on disk.
- Semantic-model engineering is delegated to Microsoft's external Modeling MCP and then wrapped with compatibility checks, policy enforcement, diagnostics, and audit logging.

More detail: [Architecture](docs/architecture.md)

## Quick Install

```powershell
git clone <repo-url>
cd powerbi-unified-mcp
npm install
npm run build
npm test
```

If Microsoft Modeling MCP is not auto-discovered:

```powershell
$env:POWERBI_MODELING_MCP_EXE="C:\path\to\powerbi-modeling-mcp.exe"
```

Run in stdio mode:

```powershell
node server.js
```

Run in HTTP mode:

```powershell
node server.js --transport=http --port=8765
```

Health check:

```powershell
curl http://127.0.0.1:8765/health
```

Full setup: [Installation](docs/getting-started/installation.md)

## MCP Client Examples

- [Generic MCP Clients](docs/clients/generic-mcp.md)
- [Codex](docs/clients/codex.md)
- [Claude](docs/clients/claude.md)
- [ChatGPT](docs/clients/chatgpt.md)

## Example Prompts

> Inspect my currently open Power BI Desktop model and summarize the tables, measures, and relationships.

> Create a Total Profit measure, validate the DAX, and query it to confirm it works.

> Open this PBIR report project and list the report pages, visuals, and active theme.

> Create an Executive Overview report page with Total Sales and Profit cards, monthly sales trend, category sales bar chart, and a Region slicer.

> Find the Sales by Category visual, change it to a clustered bar chart, move it to the right side of the page, and validate the report.

> Validate the current PBIR report and explain any errors before modifying anything.

## Security

Security modes:

- `read-only`
- `safe-write`
- `full`

Important defaults:

- report mutations are constrained to configured filesystem roots
- most report writes create automatic checkpoints by default
- destructive or security-sensitive modeling operations are policy-gated
- HTTP mode is a development transport and should be treated as local-first

Do not expose a `full` mode endpoint publicly without authentication, TLS, reverse proxying, logging, and network protections.

More detail: [Security Model](docs/security/security-model.md)

## Compatibility

- Node.js `>=20`
- Windows is the primary supported environment for live Power BI Desktop integration
- semantic-model features require Microsoft's Power BI Modeling MCP
- minimum supported upstream Modeling MCP version: `0.4.0`
- `v0.2.0` has been live-tested against a real Power BI Desktop model for discovery, connection, metadata inspection, DAX validation/execution, and temporary measure CRUD with cleanup

More detail: [Modeling MCP Compatibility](docs/modeling-mcp-compatibility.md)

## Limitations

- direct `.pbix` canvas edits are not the report-authoring path; use PBIR/PBIP projects
- semantic-model features depend on Microsoft's upstream executable
- live Desktop integration is Windows-focused
- report visual coverage is substantial but not complete

More detail: [Limitations](docs/limitations.md)

## Documentation

- [Documentation Home](docs/README.md)
- [Quickstart](docs/getting-started/quickstart.md)
- [Power BI Desktop](docs/power-bi/desktop.md)
- [Semantic Modeling](docs/power-bi/semantic-modeling.md)
- [Report Authoring](docs/power-bi/report-authoring.md)
- [Visual Catalog](docs/power-bi/visuals.md)
- [Configuration Reference](docs/reference/configuration.md)
- [Tools Reference](docs/reference/tools.md)
- [Generated Capability Matrix](docs/generated/capability-matrix.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Roadmap](docs/roadmap.md)

## Contributing

Contributor setup, test flow, metadata generation, and release expectations: [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT. See [LICENSE](LICENSE).