Power BI MCP Server

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.

---

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 (snake_case 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 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.

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 response boundary, not just per-handler).

# config/policies.yaml (excerpt)
tables:
  - name: "*"
    columns:
      - name: ssn
        action: block
      - name: card_number
        action: mask

Environment variables

---

Documentation

---

Testing

The suites in tests/ are assert-based scripts that run without Power BI (pure logic is tested directly; live connectors are mocked).

python run_tests.py

See docs/TESTING.md for what each suite covers. Live Desktop, XMLA, REST, and admin paths are doc-verified against Microsoft Learn and mock-tested; end-to-end verification of those paths needs a Windows + Power BI / Fabric environment.

---

Project structure

powerbi-mcp/
├── src/
│   ├── server.py                    # MCP server: 70 tools + resources/prompts/completion
│   ├── powerbi_desktop_connector.py # Desktop (ADOMD) + RLS + VertiPaq DMVs
│   ├── powerbi_xmla_connector.py    # Cloud XMLA
│   ├── powerbi_rest_connector.py    # REST: discovery, refresh, admin Scanner/Activity
│   ├── powerbi_tom_connector.py     # TOM writes: measures, relationships, transactions
│   ├── powerbi_pbip_connector.py    # PBIP/TMDL/PBIR offline editing (transactional)
│   ├── pbir_authoring.py            # PBIR emitters: pages, visuals, field projections
│   ├── adomd_loader.py             # Shared ADOMD.NET discovery (Desktop + XMLA)
│   ├── model_analysis.py            # BPA, AI-readiness, data dictionary, diff, DAX tests
│   ├── dax_lint.py                  # DAX anti-pattern linter + rewrite hints (tokenizer)
│   ├── svg_measures.py             # SVG micro-visual DAX measure generators
│   ├── naming_audit.py             # Naming-convention audit -> rename plan
│   ├── pbix_tools.py               # PBIX (.pbix ZIP) inspect/extract + layout decode
│   ├── bpa_authoring.py            # Custom BPA rule validation + rule-source audit
│   ├── refresh_diagnostics.py       # Refresh error classification
│   ├── governance.py                # Scanner summary + activity aggregation
│   └── security/                    # security_layer, access_policy, pii_detector, audit_logger
├── config/policies.yaml
├── tests/                           # Assert-based suites
├── docs/                            # TOOLS, ARCHITECTURE, TESTING
├── run_tests.py
├── AGENTS.md, CLAUDE.md
├── Dockerfile, requirements-core.txt
├── pyproject.toml, .editorconfig
├── CHANGELOG.md, requirements.txt
└── README.md

---

Limitations

---

Roadmap

Done

• Power BI Desktop and Service connectivity, RLS testing, TOM writes, PBIP safe editing.
• DAX validate-before-commit loop, atomic transactions, dependency and impact analysis.
• Best Practice Analyzer, AI-readiness scoring, VertiPaq-style storage and query analysis.
• Transactional, atomic, encoding-faithful PBIP renames.
• Enforced column policies, PII masking, numeric masking, tamper-evident audit, read-only mode.
• Documentation export, model snapshot and diff, pre-deploy gate, DAX regression runner.
• Refresh doctor, unused-object detection, RLS test matrix.
• Cross-workspace lineage, fleet refresh monitor, usage analytics.
• Modern MCP surface: annotations, structured output, resources, prompts, completion.
• Docker image for the cross-platform offline subset.

Planned

• Remote HTTP transport with Microsoft Entra OAuth (today, use the official remote Power BI MCP server for cloud auth).
• Best Practice Analyzer auto-fix and custom team rule packs.
• Deeper VertiPaq (per-column cardinality) and server-timings capture.
• Optional local / open-source LLM support.

---

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Keep the tool registry in sync (a tool lives in handle_list_tools, _build_tool_dispatch, and _build_tool_annotations in src/server.py; a parity check enforces this).
4. Run python run_tests.py and keep all suites green.
5. Open a pull request.

Formatting conventions are in pyproject.toml and .editorconfig.

---

Author

Sulaiman Ahmed, Data Analytics Engineer and Microsoft Certified Professional.

---

License

MIT. See LICENSE.

Acknowledgments

• Model Context Protocol by Anthropic.
• Microsoft's TOM, TMDL, and PBIR documentation.
• The Power BI community for insights on the PBIP format and semantic-model best practices.