MCP 服务器

Power BI Unified MCP

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

README

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

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

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