Powerbi Mcp

Power BI MCP Server

An enterprise-grade Model Context Protocol server for Power BI and Microsoft Fabric.

Let AI assistants inspect, query, validate, optimize, govern, and safely refactor Power BI semantic models and reports, through natural language.

> Disclaimer: This is an independent, community project. It is not affiliated with, endorsed > by, or connected to Microsoft Corporation or Anthropic.

---

What it is

Power BI MCP Server connects an AI assistant (Claude, GitHub Copilot, any MCP client) to your Power BI content through one consistent interface. It talks to a local Power BI Desktop model, a published Power BI Service dataset, or Power BI Project (PBIP) files on disk, and wraps every operation in a security and governance layer.

It exposes 70 tools plus MCP resources, prompts, and completion, and ships with 20 assert-based test suites.

| Capability | What you get | |------------|--------------| | Dual connectivity | Power BI Desktop (local) and Power BI Service (cloud) | | Natural-language DAX | Run, validate, and optimize DAX through conversation | | Safe refactoring | PBIP-based renames that update the model and the report visuals | | Report authoring (preview) | Add pages, visuals, and field bindings to PBIR reports from the agent | | DAX safety loop | Validate before committing; impact analysis; atomic transactions | | Model quality | Best Practice Analyzer, AI-readiness scoring, VertiPaq-style storage analysis | | Diagnostics and ops | Refresh-failure triage, unused-object detection, RLS test matrix | | Governance | Enforced PII and column policies, tamper-evident audit, read-only mode | | Fleet (admin) | Cross-workspace lineage, fleet refresh monitor, usage analytics | | Modern MCP | Tool annotations, structured output, resources, prompts, completion |

---

What you can do with it (in plain words)

This server is a bridge. On its own an AI assistant can only talk. This gives it a set of "hands" so it can reach into Power BI and actually do the work for you. You ask in plain English, the assistant picks the right tool, and you get an answer or a change.

It plugs into three places:

1. Power BI Desktop: the app open on your PC. It talks to the live model inside it.
2. Power BI Service: the cloud, your published datasets and workspaces.
3. PBIP files: when you save a "Power BI Project", the model and report become text files

on disk that it can edit directly, even with Desktop closed.

A few terms used below: a semantic model (dataset) is the data brain behind a report (its tables, columns, relationships, and measures). A measure is a saved calculation written in DAX (Power BI's formula language). RLS is row-level security (rules that limit which rows a user can see).

Things you can ask it to do

• Understand a model you have never seen. List tables, columns, measures (with formulas),

and relationships, or get the whole picture at once. > "Connect to my Power BI Desktop and summarize the model."

• Query your data in plain English. It turns the question into DAX and runs it.

> "What were the top 10 products by sales last quarter?"

• Write, fix, and optimize measures safely. It validates the DAX against your model

before saving, so broken formulas are caught early. It can also explain or speed up a measure. > "Create a 'Margin %' measure as profit divided by sales, formatted as a percentage."

• Rename tables, columns, or measures without breaking the report. Normal tools fix only

the model and leave visuals broken. This updates the model and the report visuals together, as one transaction that rolls back if anything fails. > "Rename the table 'Salesforce_Data' to 'Sales Force Data' everywhere."

• See what will break before you change anything. The full blast radius: every measure

that depends on an object and every report visual that uses it. > "If I delete the 'Old Revenue' measure, what depends on it?"

• Manage relationships between tables (cardinality and filter direction).
• Build report pages and visuals (preview). On a saved PBIP project it can add a page, drop

a chart, card, table, or slicer on it, and bind fields by role. It checks each field exists in the model first, picks measure vs aggregated-column automatically, and writes Power-BI-faithful PBIR files (right down to the nativeQueryRef and Sum(...) query refs Desktop itself writes). > "On the PBIP project, add an 'Overview' page with a bar chart of Sales by Region." Best Practice Analyzer (performance, DAX, naming, formatting), an AI-readiness score, storage/size analysis, and query-performance hints. > "Audit this model and give me the top issues to fix before I ship."

• Lint your DAX for performance traps. A static analyzer flags the classic anti-patterns

(FILTER over a whole table inside CALCULATE, nested CALCULATE, / instead of DIVIDE, IFERROR, EARLIER, SUMMARIZE used for aggregation, blank-suppressing + 0, and unrecognized or hallucinated function names) and hands back a concrete rewrite for each. > "Lint every measure in my model and suggest rewrites for the worst offenders."

• Standardize naming across the model. Audit table, column, and measure names and get a

rename plan (snakecase and camelCase to spaced Title Case, strip DIM/FACT_ prefixes, trim spaces), then apply it with the safe rename tools that also fix the report visuals. > "Audit naming and rename everything to Title Case without breaking the report."

• Add micro-visuals with one DAX measure. Generate a sparkline, bullet chart, progress bar,

or status pill as an inline SVG measure that renders right inside a table, matrix, or card. > "Make me a progress-bar measure for 'Margin %' against a 100% target."

• Open a real .pbix file. Inspect a .pbix (it is a ZIP package): see whether it has an

imported model or a live connection, which report format it uses, and how many pages, then extract it and get the report layout decoded to readable JSON. > "Inspect this .pbix and tell me if it has an imported model and how many pages."

• Author and govern your own quality rules. Validate a custom Best Practice Analyzer rule

set (catch bad scopes, duplicate IDs, risky auto-deletes) and audit where rules actually live: embedded in the model, ignored, or pulled from external files. > "Validate our BPARules.json and tell me which rules this model is silently ignoring."

• Clean up dead weight. Find columns and measures that nothing uses (not in any formula

and not in any visual) so you can remove clutter safely.

• Test security roles properly. Run a measure under every RLS role and get a pass/fail

matrix that flags roles seeing too much or nothing.

• Document the model automatically. Generate a data dictionary (Markdown or HTML) with a

documentation-coverage score, re-runnable any time.

• Compare versions and gate deployments. Snapshot the model, diff it later for a readable

"what changed" list, run a pre-deploy PASS/FAIL quality gate, and run DAX regression tests.

• Troubleshoot refreshes (cloud). When a refresh fails it classifies the cause (expired

credentials, gateway down, throttling, out of memory, timeout, bad source query) and tells you the fix.

• Govern access and stay compliant. Mask PII before the AI sees it, block/mask/hash/redact

specific columns, keep a tamper-evident audit log, and flip on read-only mode so an agent can look but not touch.

• See across the whole tenant (admins). Inventory every workspace, find datasets with no

security or no sensitivity label, trace which reports use a dataset, monitor refresh health, and view usage analytics.

A realistic end-to-end example

> 1. "Connect to my Power BI Desktop model." > 2. "Audit it and list the worst issues." > 3. "What would break if I rename the 'Customer ID' column?" > 4. "Rename it to 'CustomerKey' across model and report." > 5. "Create a 'YoY Sales %' measure, validate it, and format as a percentage." > 6. "Export a data dictionary so the team has docs." > 7. "Run the pre-deploy quality gate before I publish."

Each step is one sentence; the server does the real Power BI work behind it.

---

Why this server

Microsoft now ships official Power BI MCP servers (public preview): a remote one for chat-with-data and a local modeling one for authoring semantic models. This project is complementary. It leans into what those servers do not cover:

• Report-aware safe renames. The official local modeling MCP edits the model only and

cannot touch the report layer. This server renames tables, columns, and measures across both the model (TMDL) and the report (PBIR visuals, cultures, diagram), so visuals do not break.

• A real governance and security layer. Enforced column policies (block, mask, hash,

redact, numeric-mask), PII detection, a tamper-evident audit log, and a read-only lockdown mode.

• Diagnostics and fleet ops. Refresh-failure classification, unused-object cleanup, impact

analysis, an RLS test matrix, and tenant-wide lineage and usage analytics.

• Offline, PBIP-first workflows. The whole PBIP, analysis, and security subset runs

cross-platform with no Fabric capacity required.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how it fits together.

---

Quick start

Prerequisites

Live connectivity (Power BI Desktop / Service): Windows 10/11, Power BI Desktop, Python 3.10+, and the ADOMD.NET client library. Newer Power BI Desktop builds no longer ship ADOMD.NET, so install SQL Server Management Studio (SSMS) or the Microsoft.AnalysisServices.AdomdClient NuGet package, or point ADOMD_DLL_PATH at the folder containing Microsoft.AnalysisServices.AdomdClient.dll. The server searches Power BI Desktop, SSMS, the SQL Server SDK, and NuGet automatically. Cloud also needs an Azure AD service principal and, for some operations, a Premium / PPU / Fabric capacity.

Offline subset only (PBIP editing, BPA, analysis, security): any OS, Python 3.10+, no .NET.

Install

git clone https://github.com/sulaiman013/powerbi-mcp.git
cd powerbi-mcp

# Full install (Windows, for live connectivity)
pip install -r requirements.txt

# Or: offline / cross-platform subset only
pip install -r requirements-core.txt

# (Optional) cloud credentials, Windows
copy .env.example .env
# edit .env with your Azure AD service principal

Configure Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "powerbi": {
      "command": "python",
      "args": ["C:/path/to/powerbi-mcp/src/server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/powerbi-mcp/src"
      }
    }
  }
}

Run with Docker (offline, cross-platform)

The image runs the platform-independent tools (PBIP editing, BPA, AI-readiness, model analysis, security, resources, prompts) on any OS with no .NET. Live Desktop / XMLA / TOM connectivity still needs Windows + ADOMD.NET.

docker build -t powerbi-mcp .
docker run --rm -i -v /path/to/MyReport:/work powerbi-mcp

---

Tools

70 tools across the categories below. The full reference, with parameters and read / write / destructive markers, is in [docs/TOOLS.md](docs/TOOLS.md).

| Category | Count | Highlights | |----------|:-----:|------------| | Desktop (local, ADOMD) | 7 | discover, connect, list tables/columns/measures, desktop_execute_dax, model info | | Cloud (XMLA + REST) | 6 | workspaces, datasets, tables, columns, execute_dax, model info | | Security and audit | 3 | security_status, security_audit_log, verify_audit_integrity | | Row-Level Security | 3 | list roles, set role, status | | Model writes (TOM) | 7 | create_measure, delete_measure, batch_update_measures, deprecated batch renames | | DAX safety and transactions | 5 | validate_dax, scan_measure_dependencies, begin/commit/rollback transaction | | Relationships | 2 | create_relationship, delete_relationship | | PBIP safe editing | 5 | load project, get info, rename tables/columns/measures (model + report) | | PBIP diagnostics | 4 | fix broken visuals, fix DAX quoting, scan broken refs, validate | | Report authoring (PBIR, preview) | 4 | pbir_add_page, pbir_add_visual, pbir_bind_fields, pbir_validate_report | | Model quality and performance | 4 | run_bpa, audit_ai_readiness, analyze_model_storage, analyze_query_performance | | DAX quality | 2 | dax_lint (performance anti-patterns), dax_suggest_rewrite | | Authoring helpers | 2 | generate_svg_measure (sparkline/bullet/progress/pill), audit_naming | | PBIX onboarding | 2 | pbix_inspect, pbix_extract (crack open a real .pbix) | | Custom BPA governance | 2 | bpa_validate_rules, bpa_audit_rule_sources | | Documentation, diff, CI | 5 | export_data_dictionary, model_snapshot, model_diff, pre_deploy_gate, run_dax_tests | | Diagnostics and ops | 4 | refresh_doctor, find_unused_objects, impact_analysis, rls_test_harness | | Governance-ops fleet (admin) | 3 | cross_workspace_lineage, fleet_refresh_monitor, usage_and_orphan_analytics |

Resources, prompts, and completion

• Resources: powerbi://desktop/{schema,measures,bpa,ai-readiness},

powerbi://cloud/{workspace}/{dataset}/schema, powerbi://reference/{bpa-rules,refresh-errors}. Attach model context without a tool call.

• Prompts: optimize_measure, explain_measure, audit_model, document_model,

plan_safe_rename, pre_deploy_review. Ready-made, tool-orchestrated playbooks.

• Completion: grounds prompt and resource arguments in real table and measure names from

the connected model.

• Annotations and structured output: every tool declares safety hints

(readOnlyHint, destructiveHint); key tools return typed structuredContent.

---

Safe renames: the two-layer problem

Power BI stores a model layer and a report layer separately. TOM (and the official modeling MCP) can edit the model, but cannot update report visuals, so a TOM rename leaves visuals pointing at the old name. This server solves it with PBIP file editing: it rewrites the TMDL model files and the PBIR report files (visual bindings, cultures, diagram) together, so nothing breaks.

User: "Load PBIP project from C:/Projects/SalesReport"
User: "Rename table Salesforce_Data to Sales Force Data"

The rename cascade is transactional (it rolls every file back on failure) and writes atomically (temp file plus os.replace), preserving encoding and line endings.

> Always use the pbip_rename_* tools for renames, not the deprecated TOM batch_rename_* > tools. Close Power BI Desktop before PBIP edits, then reopen.

---

Security and governance

• PII detection and masking before results reach the AI (SSN, credit card, email, phone, IP).
• Enforced column and table policies from config/policies.yaml: block, mask, hash,

redact, and numeric_mask (session-randomized scaling that hides values but preserves ratios).

• Audit logging with a tamper-evident hash chain; verify it with verify_audit_integrity.

Set POWERBI_MCP_AUDIT_KEY to switch the chain to HMAC-SHA256 (cryptographically strong against an attacker who edits the log); without a key it is a plain SHA-256 chain that still catches accidental edits and naive tampering.

• Read-only / lockdown mode: set POWERBI_MCP_READONLY=true to refuse every write tool

(model/report mutations and file-writing tools like snapshots, dictionaries, and PBIX extraction) while reads and diagnostics keep working. Ideal for shared or autonomous agent use.

• Connection-string secrets and PII are redacted from logs, error messages, the audit log, and

every tool response (redaction is applied at the respons

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sulaiman013
• Source: sulaiman013/powerbi-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.