Skip to content
Back to search

powerbi-mcp

MCP server for natural language interaction with Power BI datasets

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sulaiman013/powerbi-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sulaiman013/powerbi-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sulaiman013--powerbi-mcp/badge.svg)](/listings/sulaiman013--powerbi-mcp)

HTML

<a href="/listings/sulaiman013--powerbi-mcp"><img src="/api/listings/sulaiman013--powerbi-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

**Live connectivity (Power BI Desktop / Service):** Windows 10/11, Power BI Desktop, Python 3.10+, and the ADOMD.NET client library (plus AMO/TOM for live writes). Newer Power BI Desktop builds no longer ship these, so install SQL Server Management Studio (SSMS), or grab both NuGet packages once and point the server at them:

# one-time: fetch ADOMD + AMO/TOM from NuGet and extract the DLLs
curl -L -o adomd.nupkg "https://www.nuget.org/api/v2/package/Microsoft.AnalysisServices.AdomdClient.retail.amd64"
curl -L -o amo.nupkg   "https://www.nuget.org/api/v2/package/Microsoft.AnalysisServices.retail.amd64"
# unzip both (they are ZIP files) and copy lib/net45/*.dll into one folder, e.g. C:\pbi-dlls
# then set:  ADOMD_DLL_PATH=C:\pbi-dlls

The server also searches Power BI Desktop, the GAC, SSMS, the SQL Server SDK, and the NuGet cache automatically (`ADOMD_DLL_PATH` / `TOM_DLL_PATH` override). Cloud additionally needs an Azure AD service principal and, for some operations, a Premium / PPU / Fabric capacity.

**Desktop Bridge tools (hot-reload, screenshots):** Power BI Desktop June 2026 or later with the preview option "Enable external tool access to Power BI Desktop through secure local APIs" (File > Options > Preview features; on by default).

**Offline subset only (PBIP/TMDL/PBIR authoring and editing, BPA, linters, 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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 524 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Power BI MCP Server
  2. <p align="center">
  3. <strong>A Python MCP server that lets an AI agent query, change, build and check Power BI models and reports.</strong>
  4. </p>
  5. <p align="center">
  6. <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.9.0-blue?style=flat-square" alt="Version 3.9.0"></a>
  7. <a href="docs/TOOLS.md"><img src="https://img.shields.io/badge/Tools-94-purple?style=flat-square" alt="94 tools"></a>
  8. <a href="https://github.com/sulaiman013/powerbi-mcp/actions/workflows/tests.yml"><img src="https://github.com/sulaiman013/powerbi-mcp/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
  9. <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.10%2B-green?style=flat-square" alt="Python 3.10+"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="MIT license"></a>
  11. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blue?style=flat-square" alt="MCP compatible"></a>
  12. </p>
  13. powerbi-mcp gives an AI assistant (Claude, GitHub Copilot or any other MCP client) **94 tools**
  14. for Power BI. With them the assistant can query semantic models, change them safely, build whole
  15. reports from one JSON spec, build custom visuals, and open the result in Power BI Desktop to take
  16. a screenshot and check its own work. It is for Power BI developers and BI leads who want an
  17. assistant that does the work, and for agent developers who need Power BI tools.
  18. > **Disclaimer:** an independent community project, not affiliated with, endorsed by, or
  19. > connected to Microsoft Corporation or Anthropic.
  20. ## Contents
  21. - [What's new in 3.9](#whats-new-in-39)
  22. - [From v1.0 to v3.9](#from-v10-to-v39)
  23. - [What you can do](#what-you-can-do)
  24. - [How it works](#how-it-works)
  25. - [Quick start](#quick-start)
  26. - [Tools at a glance](#tools-at-a-glance)
  27. - [Key workflows](#key-workflows)
  28. - [Security and governance](#security-and-governance)
  29. - [Testing and verification](#testing-and-verification)
  30. - [Limitations](#limitations)
  31. - [Project structure](#project-structure)
  32. - [Documentation](#documentation)
  33. - [Roadmap](#roadmap)
  34. - [Contributing](#contributing)
  35. - [Author](#author)
  36. - [License](#license)
  37. ## What's new in 3.9
  38. - **Power BI's own report features in the report spec:** filters on the report, a page or a
  39. visual, drillthrough pages with a back button, report-page tooltips, visual interactions, the
  40. phone layout and bookmark groups. A filter someone adds in Desktop survives the next apply.
  41. - **Custom visuals without the toolchain.** `build_custom_visual` packages a real `.pbiviz` from a
  42. short definition and a render function, with click to cross-filter, cross-highlighting,
  43. right-click drill through and Power BI tooltips built in.
  44. - **Deneb charts with interactivity wired in.** `generate_deneb_spec` writes Vega-Lite specs for
  45. ten chart kinds and small multiples, with cross-filter, cross-highlight, tooltips and the
  46. context menu.
  47. - **Open, then look closer.** `bridge_open` opens a `.pbip` or `.pbix` in Desktop and waits until
  48. it is ready; `bridge_screenshot` can capture one visual instead of a whole page.
  49. - **A live pass against Power BI Desktop 2.159** found and fixed real faults: the bridge tools
  50. failed on current Desktop, machines with only the .NET (Core) client libraries could not
  51. connect, and a 260-character path stopped Desktop with a dialog the bridge cannot see.
  52. - **A report audit that knows the new features:** unreachable drillthrough pages, unused tooltip
  53. pages, partial phone layouts, and which visuals are certified.
  54. Upgrading a 3.8 spec: a tooltip page with no size is now 320 x 240, and a few inputs 3.8 accepted
  55. are now refused. See the [changelog](CHANGELOG.md).
  56. ## From v1.0 to v3.9
  57. The project started in November 2025 as a small read-only server for cloud models.
  58. | | v1.0 (Nov 2025) | v3.9 (Nov 2026) |
  59. |---|---|---|
  60. | Tools | 7 | 94 |
  61. | Works with | Power BI Service only (PPU or Premium workspaces) | Power BI Desktop, Power BI Service, PBIP files on disk, and the running Desktop window |
  62. | Can change | Nothing (read-only) | Live models (measures, relationships, in transactions), PBIP files offline (renames, measures, date tables, calculation groups, whole reports), custom visual packages |
  63. | Checks its work | No | Validates DAX before saving, dry-runs file changes, reloads and screenshots the report in Desktop |
  64. | Tests | None | 53 suites with 7,141 checks; CI on Windows and Linux |
  65. | Code size | About 2,000 lines of Python | About 37,800 lines of Python in `src/` |
  66. Tool count by release: 7 (v1.0) → 30 (v2.0) → 58 (v3.0) → 82 (v3.7) → 90 (v3.8) → 94 (v3.9).
  67. ## What you can do
  68. A few terms first. A **semantic model** is the data model behind a report (tables, relationships,
  69. measures). A **measure** is a saved formula in **DAX**, Power BI's formula language. **PBIP**
  70. (Power BI Project) saves the model (as TMDL) and the report (as PBIR) as text files. **RLS** is
  71. row-level security.
  72. **Explore and query.** List tables, columns, measures and relationships, or ask a question in
  73. plain words and let the agent write and run the DAX, on Desktop or a published model.
  74. > "Connect to my Power BI Desktop and show me the top 10 products by sales last quarter."
  75. **Check model quality.** A Best Practice Analyzer (33 rules), an AI-readiness score, storage
  76. analysis, a DAX linter with rewrites, a star-schema audit, an orphan-key scan, a naming audit, and
  77. a search for columns and measures nothing uses.
  78. > "Audit this model and give me the top issues to fix before I ship."
  79. **Change models safely.** DAX is checked against the model before it is saved, and edits can be
  80. held in a transaction. Generate measure suites (time intelligence, ratios, ranks), date tables,
  81. calculation groups and hierarchies, live or straight into PBIP files.
  82. > "Generate the time-intelligence measures for 'Total Sales' over Date[Date] and add them to the model."
  83. **Rename safely across model and report.** A rename updates the model and every visual, filter
  84. and bookmark that uses the name, in one change that writes all files or none.
  85. > "What uses the 'Customer ID' column? Rename it to 'Customer Key' everywhere."
  86. **Build reports as code.** Describe the report once in a JSON spec and the server writes the
  87. files. Applying it again changes nothing; a mistake stops the apply before any file is written.
  88. It also generates HTML and SVG measures, audits a report's design and stages it for publishing.
  89. > "Build a two-page report from this spec, with a drillthrough page for customer segment."
  90. **Custom visuals and Deneb.** Build a real `.pbiviz` from a short definition, or generate a Deneb
  91. chart. Unlike an HTML measure, both cross-filter the page on click and offer drill through.
  92. > "Turn this ranked list into a custom visual I can click to filter the page."
  93. **See and verify in Power BI Desktop.** Through Microsoft's Desktop Bridge (Desktop June 2026 or
  94. later) the agent opens a report, hot-reloads it after editing the files, and takes screenshots.
  95. > "Add the chart, reload Desktop, and screenshot the page so you can check the layout."
  96. **Security and governance.** Tools that run your DAX accept queries only and apply column
  97. policies, PII masking and an audit log. A read-only mode lets an agent look but not touch.
  98. > "Show me the security status and check that the audit log has not been changed."
  99. **Operations and fleet.** Diff a model against a snapshot, run a pre-deploy gate and DAX
  100. regression tests, explain a failed refresh, test every RLS role; admins get tenant-wide lineage.
  101. > "Why did the last refresh fail, and what should I do about it?"
  102. ## How it works
  103. Your MCP client starts the server on your machine and talks to it over stdio. Every call passes
  104. one request boundary (read-only gate, query guard, access policies, secret redaction), then takes
  105. one of four paths. The live paths need Windows; the PBIP path runs on any OS.
  106. ```mermaid
  107. flowchart LR
  108. agent["AI agent<br/>(any MCP client)"]
  109. server["powerbi-mcp<br/>request boundary + 94 tools"]
  110. desktop["Power BI Desktop<br/>local model"]
  111. service["Power BI Service<br/>published models"]
  112. pbip["PBIP project<br/>TMDL + PBIR files"]
  113. bridge["Desktop Bridge<br/>the running Desktop window"]
  114. agent -->|"tool calls over stdio"| server
  115. server -->|"DAX queries (ADOMD.NET)<br/>live model edits (TOM)"| desktop
  116. server -->|"DAX over XMLA<br/>REST and admin APIs"| service
  117. server -->|"reads and rewrites files<br/>offline, no Power BI needed"| pbip
  118. server -->|"open, hot-reload, screenshot<br/>(local named pipe)"| bridge
  119. ```
  120. Microsoft ships official Power BI MCP servers in preview: a remote one for chatting with data and
  121. a local one for authoring semantic models. This project complements them with renames that also
  122. fix the report, reports built from a spec, an access-policy layer, RLS testing, and offline PBIP
  123. work with no Fabric capacity. Details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  124. ## Quick start
  125. ### 1. Requirements
  126. | To use | You need |
  127. |---|---|
  128. | Offline tools (PBIP editing, report spec, generators, linters, audits, security) | Any OS, Python 3.10+ |
  129. | Power BI Desktop live (queries, validation, live edits) | Windows 10/11, Power BI Desktop, Python 3.10+, ADOMD.NET (plus AMO/TOM for edits) |
  130. | Desktop Bridge (open, hot-reload, screenshots) | Power BI Desktop June 2026 or later, preview option "Enable external tool access to Power BI Desktop through secure local APIs" (File > Options > Preview features; on by default) |
  131. | Power BI Service | An Azure AD service principal; XMLA needs Premium, PPU or Fabric capacity |
  132. Both requirement files pin the MCP Python SDK to `mcp>=1.10.0,<2`; the server does not run on
  133. mcp 2.x yet and says so at start-up.
  134. **Analysis Services client libraries (live connectivity only).** Newer Power BI Desktop builds no
  135. longer ship ADOMD.NET. Install SQL Server Management Studio (SSMS), or fetch both NuGet packages
  136. once and point the server at them:
  137. ```bash
  138. # one-time: fetch ADOMD + AMO/TOM from NuGet and extract the DLLs
  139. curl -L -o adomd.nupkg "https://www.nuget.org/api/v2/package/Microsoft.AnalysisServices.AdomdClient.retail.amd64"
  140. curl -L -o amo.nupkg "https://www.nuget.org/api/v2/package/Microsoft.AnalysisServices.retail.amd64"
  141. # unzip both (they are ZIP files) and copy lib/net45/*.dll into one folder, e.g. C:\pbi-dlls
  142. # then set: ADOMD_DLL_PATH=C:\pbi-dlls
  143. ```
  144. The server also searches Power BI Desktop, the GAC, SSMS, the SQL Server SDK and the NuGet cache
  145. by itself; `ADOMD_DLL_PATH` and `TOM_DLL_PATH` override the search.
  146. ### 2. Install
  147. ```bash
  148. git clone https://github.com/sulaiman013/powerbi-mcp.git
  149. cd powerbi-mcp
  150. pip install -r requirements.txt # full install (Windows, live connectivity)
  151. ```
  152. For the offline subset on any OS, install `requirements-core.txt` instead.
  153. ### 3. Connect your MCP client
  154. For Claude Desktop, add this to `%APPDATA%\Claude\claude_desktop_config.json` (with the absolute
  155. path of your clone), then restart Claude Desktop:
  156. ```json
  157. {
  158. "mcpServers": {
  159. "powerbi": {
  160. "command": "python",
  161. "args": ["C:/path/to/powerbi-mcp/src/server.py"],
  162. "env": {
  163. "PYTHONPATH": "C:/path/to/powerbi-mcp/src"
  164. }
  165. }
  166. }
  167. }
  168. ```
  169. Other MCP clients that start local stdio servers take the same command, arguments and
  170. environment in their own settings.
  171. ### 4. Your first five minutes
  172. Open a report in Power BI Desktop, then ask:
  173. 1. "Find my open Power BI Desktop and connect to it."
  174. 2. "Summarize the model: tables, measures and relationships."
  175. 3. "Run the Best Practice Analyzer and list the five most important issues."
  176. 4. "Lint every measure and suggest a rewrite for the worst one."
  177. 5. "Which file is open in Desktop? Take a screenshot of the first page." (needs the Desktop Bridge)
  178. None of these change your model or your report.
  179. ### 5. Optional: Power BI Service credentials
  180. ```bash
  181. cp .env.example .env # Windows: copy .env.example .env
  182. ```
  183. Fill in `TENANT_ID`, `CLIENT_ID` and `CLIENT_SECRET` for a service principal. The server reads
  184. `.env` at start-up; every setting in it is optional, and Desktop and PBIP work need none of them.
  185. ### 6. Optional: Docker (offline subset)
  186. The image runs the platform-independent tools (PBIP editing, the report spec, BPA, model
  187. analysis, security, resources and prompts) with no .NET. Mount your PBIP project at `/work`:
  188. ```bash
  189. docker build -t powerbi-mcp .
  190. docker run --rm -i -v /path/to/MyReport:/work powerbi-mcp
  191. ```
  192. ## Tools at a glance
  193. 94 tools in total. The counts come from the sections of [docs/TOOLS.md](docs/TOOLS.md), which
  194. lists every tool with its read, write or destructive mark.
  195. | Area (sections in docs/TOOLS.md) | Count | Main tools |
  196. |---|:-:|---|
  197. | Connect and query: Desktop (7), Cloud (6) | 13 | `desktop_connect`, `desktop_execute_dax`, `desktop_get_model_info`, `list_workspaces`, `execute_dax` |
  198. | Security and audit (3), Row-Level Security (3) | 6 | `security_status`, `verify_audit_integrity`, `desktop_set_rls_role` |
  199. | Live changes: Model writes via TOM (7), DAX safety loop and transactions (5), Relationships (2) | 14 | `validate_dax`, `create_measure`, `tom_begin_transaction`, `tom_commit_transaction`, `create_relationship` |
  200. | Offline PBIP: safe editing (6), diagnostics and repair (4) | 10 | `pbip_load_project`, `pbip_rename_tables`, `pbip_rename_columns`, `pbip_rename_measures`, `pbip_undo` |
  201. | Model authoring: Bulk DAX creation (3), Data modelling (3), Authoring helpers (2) | 8 | `generate_measure_suite`, `pbip_add_measures`, `pbip_create_date_table`, `pbip_add_calculation_group` |
  202. | Reports: Report authoring (4), Report as code (7) | 11 | `pbir_apply_spec`, `audit_report_design`, `generate_html_measure`, `pbip_stage_publish` |
  203. | Custom visuals and Deneb (3) | 3 | `build_custom_visual`, `inspect_custom_visual`, `generate_deneb_spec` |
  204. | Quality: Model quality and performance (4), DAX quality (2), Custom BPA governance (2), Warehouse audit (2) | 10 | `run_bpa`, `audit_ai_readiness`, `dax_lint`, `audit_star_schema`, `scan_referential_integrity` |
  205. | Power BI Desktop Bridge (5) | 5 | `bridge_open`, `bridge_status`, `bridge_reload`, `bridge_screenshot` |
  206. | Operations: Documentation, diff and CI (5), Diagnostics and ops (4), PBIX onboarding (2) | 11 | `model_diff`, `pre_deploy_gate`, `run_dax_tests`, `refresh_doctor`, `impact_analysis`, `pbix_inspect` |
  207. | Governance-ops fleet, admin only (3) | 3 | `cross_workspace_lineage`, `fleet_refresh_monitor`, `usage_and_orphan_analytics` |
  208. | **Total** | **94** | |
  209. <details>
  210. <summary>Resources, prompts, completion and annotations</summary>
  211. - **Resources:** `powerbi://desktop/schema`, `.../measures`, `.../bpa`, `.../ai-readiness`, the
  212. template `powerbi://cloud/{workspace}/{dataset}/schema`, `powerbi://reference/bpa-rules` and
  213. `powerbi://reference/refresh-errors`.
  214. - **Prompts:** `optimize_measure`, `explain_measure`, `audit_model`, `document_model`,
  215. `plan_safe_rename`, `pre_deploy_review`. **Completion** fills prompt and resource arguments.
  216. - **Annotations:** every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` and
  217. `openWorldHint`, so a client can approve reads and confirm writes; 33 return `structuredContent`.
  218. </details>
  219. ## Key workflows
  220. ### Safe renames
  221. Power BI keeps the model and the report in separate files. A rename through the live model (TOM)
  222. changes the model but not the report, so every visual that used the old name breaks. The
  223. `pbip_rename_*` tools rewrite both layers in one all-or-nothing change.
  224. ```text
  225. You: Load the PBIP project in C:/Projects/SalesReport.
  226. You: Rename the table Salesforce_Data to Sales Force Data.
  227. Agent: pbip_load_project -> pbip_rename_tables -> bridge_reload
  228. ```
  229. Nothing is written if the old name is missing, the new name collides, or a reference would break.
  230. Files keep their encoding and line endings, text that only mentions the name (a title) is listed
  231. for review, and `pbip_undo` restores the previous state. Do not use the deprecated
  232. `batch_rename_*` tools.
  233. ### Report as code
  234. This spec builds an overview page with a year filter, and a drillthrough page for segment:
  235. ```json
  236. {
  237. "pages": [
  238. {"name": "overview", "display_name": "Overview",
  239. "filters": [{"field": "Calendar.Year", "in": [2025, 2026]}],
  240. "elements": [
  241. {"name": "by_segment", "type": "visual", "visual_type": "barChart",
  242. "x": 24, "y": 24, "width": 600, "height": 400,
  243. "fields": {"Category": "Customer.Segment", "Y": "Sales.Total Sales"}}]},
  244. {"name": "detail", "display_name": "Segment detail",
  245. "drillthrough": {"fields": ["Customer.Segment"], "back_button": true},
  246. "elements": [
  247. {"name": "orders", "type": "visual", "visual_type": "tableEx",
  248. "x": 24, "y": 72, "width": 1232, "height": 600,
  249. "fields": {"Values": [{"column": "Customer.Name"}, {"measure": "Sales.Total Sales"}]}}]}
  250. ]
  251. }
  252. ```
  253. Ask the agent to run `pbir_apply_spec` with `dry_run: true` first, then for real. Every field is
  254. checked against the model before a file is written, and pages the spec did not create are never
  255. touched. The full format is in [docs/REPORT_SPEC.md](docs/REPORT_SPEC.md).
  256. ### Build a custom visual
  257. A definition names the data roles and a render function returns HTML. An element with `data-row`
  258. becomes a data point: click cross-filters, right-click offers drill through, hover shows the
  259. tooltip.
  260. ```json
  261. {
  262. "name": "simpleList",
  263. "display_name": "Simple list",
  264. "author": {"name": "Your name"},
  265. "roles": [
  266. {"name": "category", "kind": "grouping"},
  267. {"name": "value", "kind": "measure", "max": 1}
  268. ],
  269. "css": ".row { padding: 4px 8px; } .row.vk-selected { font-weight: 600; }",
  270. "js_files": ["render.js"]
  271. }
  272. ```
  273. ```javascript
  274. // render.js, next to definition.json
  275. function render(ctx) {
  276. return ctx.rows.map(function (row) {
  277. return '<div class="row" data-row="' + row.index + '">' +
  278. ctx.escape(row.text.category) + ': ' + ctx.escape(row.text.value) + '</div>';
  279. }).join("");
  280. }
  281. ```
  282. `build_custom_visual` turns it into a `.pbiviz`. To build and place it in one step, list it in a
  283. report spec, `"custom_visuals": [{"definition": "visuals/simple_list/definition.json", "alias": "simple"}]`,
  284. and give a visual element `"custom": "simple"`. Four complete visuals are in
  285. [examples/custom_visuals/](examples/custom_visuals/).
  286. ### Edit, reload, screenshot
  287. With Power BI Desktop June 2026 or later, the agent checks its own work in the running app:
  288. ```text
  289. bridge_open open the project in Desktop and wait for the bridge (skip if it is open)
  290. bridge_status which file is open, unsaved changes, pages, the Analysis Services port
  291. pbip_* / pbir_* tools edit offline: measures, date table, pages, visuals, the whole spec
  292. bridge_reload hot-reload the open file from disk; no close and reopen
  293. bridge_screenshot PNG of each page, or of one visual, for the agent to look at and fix
  294. ```
  295. `bridge_reload` refuses to run over unsaved Desktop changes unless you pass `force=true`.
  296. ## Security and governance
  297. - **Query-only.** Tools that run your DAX accept DAX queries only; TMSL, XMLA and MDX are refused.
  298. - **Column and table policies** in [config/policies.yaml](config/policies.yaml): block, mask,
  299. hash, redact or numeric-mask a column; cap rows or require a filter on a table. They follow
  300. aliases and measures, and every tool that runs DAX applies them.
  301. - **Fail closed.** A missing or invalid policy file refuses queries; `security_status` says why.
  302. - **PII masking** on results (SSN, credit card, email, phone, IP address), with value checks so
  303. dates and ordinary text are left alone.
  304. - **Audit log** with a hash chain (`verify_audit_integrity`); `POWERBI_MCP_AUDIT_KEY` makes it
  305. HMAC-SHA256, and without a key it only catches accidental edits.
  306. - **Secret redaction** on every response and in the logs.
  307. **Read-only mode:** set `POWERBI_MCP_READONLY=true` in `.env` or in the `env` block of your MCP
  308. client config. Every tool that changes a model, a report or a file is then refused; reads keep
  309. working. A value that cannot be read as true or false also turns it on.
  310. The policies work on query text and result names: defence in depth, not a security boundary.
  311. Row-level and object-level security in the semantic model is the boundary.
  312. <details>
  313. <summary>Essential environment variables</summary>
  314. | Variable | Purpose |
  315. |---|---|
  316. | `TENANT_ID`, `CLIENT_ID`, `CLIENT_SECRET` | Service principal for the Power BI Service tools |
  317. | `ADOMD_DLL_PATH` | Folder (or full path) of `Microsoft.AnalysisServices.AdomdClient.dll`, if the search misses it |
  318. | `TOM_DLL_PATH` | Folder (or full path) of `Microsoft.AnalysisServices.Tabular.dll` for live edits (`ADOMD_DLL_PATH` is searched too) |
  319. | `PYTHONNET_RUNTIME` | `coreclr` when only the .NET (Core) builds of ADOMD/TOM are installed |
  320. | `POWERBI_MCP_READONLY` | Refuse every tool that changes something. Accepts 1/true/yes/on |
  321. | `POWERBI_MCP_QUERY_TIMEOUT` | Seconds before a DAX query is cancelled (default 120) |
  322. | `POWERBI_MCP_POLICY_FILE` | Your own policy file instead of `config/policies.yaml`; missing or invalid means queries are refused |
  323. | `POWERBI_MCP_AUDIT_KEY` | Secret that switches the audit hash chain to HMAC-SHA256 |
  324. | `POWERBI_MCP_PBIP_BACKUPS` | `false` stops the automatic project backup before a rename or repair |
  325. | `LOG_LEVEL` | `DEBUG` turns on argument logging (secrets redacted) |
  326. The full list is in [docs/TOOLS.md](docs/TOOLS.md#environment-variables);
  327. [.env.example](.env.example) has every setting with a comment.
  328. </details>
  329. ## Testing and verification
  330. The 53 suites in `tests/` are plain assert-based Python scripts. They need no Power BI, ADOMD or
  331. .NET: pure logic is tested directly, the server and live connectors run against fakes.
  332. ```bash
  333. python run_tests.py # all suites
  334. python run_tests.py rename dax # only suites whose file name contains one of these words
  335. python tests/test_docs_parity.py # one suite
  336. ```
  337. A suite fails if it exits non-zero or prints a failed check. CI
  338. ([tests.yml](.github/workflows/tests.yml)) runs every suite on each push to `master` and each
  339. pull request, on Windows and Linux with Python 3.10, 3.12 and 3.13.
  340. | Verified | How |
  341. |---|---|
  342. | Pure logic: tokenizer, renames, report spec, generators, linters, auditors, security | 53 suites, 7,141 checks |
  343. | Rename engine, report spec, report audit | Also run on copies of real, complex reports; renames and the spec checked byte for byte |
  344. | Desktop live tools | Run against Power BI Desktop 2.159 on 2026-11-11: connect, DAX, `validate_dax`, model audits, a TOM transaction rolled back, the bridge (open, reload, page and single-visual screenshots) |
  345. | Generated reports, Deneb charts, built custom visuals | Loaded and drawn in Desktop 2.159; a built visual's selection, highlight, tooltip and context-menu calls were answered by the real host |
  346. **Not verified:**
  347. - **Clicks and hovering.** The bridge cannot click or hover, so clicking to filter, drilling
  348. through, tooltip pages on hover and the phone view were not observed. Click through once.
  349. - **Generated DAX and M** are checked for shape and lint, not run by an engine. Use `validate_dax`.
  350. - **The cloud paths** (XMLA, REST, admin APIs) are tested with fakes and checked against
  351. Microsoft Learn; they have not run against a tenant. Not every Desktop tool ran live either,
  352. and the rename engine has not been re-run live since its 3.8 rewrite.
  353. Details: [docs/TESTING.md](docs/TESTING.md).
  354. ## Limitations
  355. | Limitation | Notes |
  356. |---|---|
  357. | Live connectivity is Windows only | ADOMD.NET, TOM and the bridge's named pipe need Windows. The offline subset runs anywhere, also in Docker. |
  358. | A live (TOM) rename breaks report visuals | Use the `pbip_rename_*` tools, which update the report too. |
  359. | The Desktop Bridge is a preview | Its protocol changed in Desktop 2.159; the client follows the running build's manifest, but a later build can change it again. A single-visual screenshot needs `report.snapshot.capture/v2`. The bridge cannot click or save. |
  360. | Some visuals are not certified | Private `.pbiviz` visuals (built ones included) and HTML Content Regular are blocked where only certified visuals are allowed. Deneb (AppSource edition) and HTML Content Secure are certified. |
  361. | The custom visual runtime is small on purpose | One categorical data mapping: no table or matrix mapping, no per-point conditional formatting, no localisation. |
  362. | Cloud tools need the right capacity and rights | XMLA needs Premium, PPU or Fabric capacity (basic refresh history works on Pro). The fleet tools need Fabric admin or a service principal allowed to use the read-only admin APIs. |
  363. | No storage-engine timings | `analyze_query_performance` gives duration and hints; use DAX Studio for formula- versus storage-engine timings. |
  364. ## Project structure
  365. ```text
  366. powerbi-mcp/
  367. ├── src/
  368. │ ├── server.py MCP server: tool registry, request boundary, handlers
  369. │ ├── powerbi_*_connector.py Desktop (ADOMD), XMLA, REST, TOM and PBIP connectors
  370. │ ├── desktop_bridge.py Desktop Bridge client (JSON-RPC over a named pipe)
  371. │ ├── pbip_rename.py rename engine (with pbip_report, pbip_json, pbip_mquery, tmdl_scan)
  372. │ ├── report_spec.py report as code (with pbir_builders, pbir_filters, report_audit)
  373. │ ├── custom_visual.py .pbiviz builder; visual_kit/ holds the visual's runtime
  374. │ ├── dax_tokens.py, safe_io.py shared DAX tokenizer, atomic file writes
  375. │ └── security/ policies, PII masking, audit log, redaction
  376. ├── config/policies.yaml access policies
  377. ├── examples/custom_visuals/ four example visual definitions
  378. ├── tests/ + run_tests.py assert-based suites and their runner
  379. ├── docs/ TOOLS, REPORT_SPEC, ARCHITECTURE (full file map), TESTING
  380. └── Dockerfile, requirements*.txt, AGENTS.md, CHANGELOG.md
  381. ```
  382. ## Documentation
  383. | Document | Contents |
  384. |---|---|
  385. | [docs/TOOLS.md](docs/TOOLS.md) | Every tool with its safety mark, plus resources, prompts and environment variables |
  386. | [docs/REPORT_SPEC.md](docs/REPORT_SPEC.md) | The report spec behind `pbir_apply_spec`, with a full example |
  387. | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Components, request boundary, security layer, file map |
  388. | [docs/TESTING.md](docs/TESTING.md) | How to run the suites, what each covers, what was verified live |
  389. | [AGENTS.md](AGENTS.md) | Playbook for agents: golden rules, workflows, choosing a visual technique |
  390. | [CHANGELOG.md](CHANGELOG.md) | Every change, by release |
  391. | [examples/custom_visuals/](examples/custom_visuals/) | Four custom visual definitions to build from |
  392. ## Roadmap
  393. - A trace-based DAX optimization loop (formula- versus storage-engine timings).
  394. - Refresh trigger, monitor and cancel.
  395. - PyPI packaging and tagged releases.
  396. - Live runs of the cloud paths against a tenant, and a way to click through generated reports.
  397. - Report spec: data state inside bookmarks. Custom visuals: table and matrix mappings.
  398. - A port to the mcp SDK 2.x, and a remote HTTP transport with Microsoft Entra sign-in.
  399. ## Contributing
  400. 1. Fork the repository and create a feature branch.
  401. 2. Register a new tool in `build_tools`, `_build_tool_dispatch` and `_build_tool_annotations` in
  402. `src/server.py`, and in `docs/TOOLS.md`. Parity tests check both.
  403. 3. Read and rewrite DAX through `src/dax_tokens.py`; write files through `src/safe_io.py`.
  404. 4. Run `python run_tests.py`, keep every suite green, and open a pull request.
  405. Formatting conventions are in `pyproject.toml` and `.editorconfig`.
  406. ## Author
  407. **Sulaiman Ahmed**, Data Analytics Engineer and Microsoft Certified Professional.
  408. [![GitHub](https://img.shields.io/badge/GitHub-sulaiman013-181717?style=flat-square&logo=github)](https://github.com/sulaiman013)
  409. [![Portfolio](https://img.shields.io/badge/Portfolio-sulaiman--ahmed-blue?style=flat-square&logo=google-chrome)](https://sulaiman-ahmed.lovable.app)
  410. ## License
  411. MIT. See [LICENSE](LICENSE).
  412. **Acknowledgments:** the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic;
  413. Microsoft's TOM, TMDL and PBIR documentation; and the Power BI community, for insights on the
  414. PBIP format and semantic-model best practices.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.