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.

Related MCP server: powerbi-mcp-local

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

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

Quick Install

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

If Microsoft Modeling MCP is not auto-discovered:

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

Run in stdio mode:

node server.js

Run in HTTP mode:

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

Health check:

curl http://127.0.0.1:8765/health

Full setup: Installation

MCP Client Examples

• Generic MCP Clients

• Codex

• Claude

• ChatGPT

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

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

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

Documentation

• Documentation Home

• Quickstart

• Power BI Desktop

• Semantic Modeling

• Report Authoring

• Visual Catalog

• Configuration Reference

• Tools Reference

• Generated Capability Matrix

• Troubleshooting

• Roadmap

Contributing

Contributor setup, test flow, metadata generation, and release expectations: CONTRIBUTING.md

License

MIT. See LICENSE.