pbi-webview2 — MCP server for the live Power BI Desktop report canvas

pbi-webview2 is a Model Context Protocol server that drives Power BI Desktop's WebView2 report canvas over CDP (Chrome DevTools Protocol). It turns an AI agent (Claude Code, Claude Desktop, or any MCP client) into a hands-on tester of your running report: switch pages, click slicers and buttons, fire bookmarks by name, read cards and matrices as structured data, judge whether a cross-filter fired, scan for broken visuals, run the Performance Analyzer, capture and compare value baselines, and screenshot individual visuals.

Why

Power BI Desktop renders its report canvas inside an embedded WebView2 (Chromium). When Desktop is launched with the WebView2 remote-debugging port enabled, that canvas is a real DOM you can attach to over CDP. pbi-webview2 exploits this to interact with the live report — no reload, no re-render, no screenshot-OCR to guess at numbers. Every tool reads values straight from the DOM, and clicks are trusted OS-level input that Desktop actually reacts to (synthetic DOM events are ignored by the canvas). Selectors and behavioural traps were verified against Power BI Desktop 2.155 (July 2026).

Each tool is one full, verified recipe (tag the target element in-page, then act on it by a data-pw selector) rather than a raw primitive — so the agent gets a clean result object ({connected:true, ...}) instead of having to rediscover the DOM every time.

Related MCP server: Chrome DevTools MCP

Requirements

• Windows — Power BI Desktop is Windows-only, and so is this server (os: win32).

• Power BI Desktop installed (as PBIDesktop.exe or the Microsoft Store version).

• Node.js ≥ 20.

• Optional: Microsoft's @microsoft/powerbi-desktop-bridge-cli (only if you prefer the bridge CLI over the built-in direct PBIDesktop.exe launch — see pbi_launch below).

Install / registration

The server runs straight from npm via npx; nothing to clone.

Claude Code

claude mcp add pbi-webview2 -- npx -y pbi-webview2

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pbi-webview2": {
      "command": "npx",
      "args": ["-y", "pbi-webview2"]
    }
  }
}

Generic MCP client / from source

Any client that speaks stdio MCP can launch it. To run from a local checkout instead of npm:

{
  "mcpServers": {
    "pbi-webview2": {
      "command": "node",
      "args": ["C:/path/to/pbi-webview2/server.js"],
      "env": { "PBI_CDP_ENDPOINT": "http://127.0.0.1:9222" }
    }
  }
}

The server connects lazily — it boots fine with Desktop closed, and every tool returns a structured {connected:false, error, hint} (never a thrown error) until Desktop is reachable. So you can register it once and launch Desktop later.

Quickstart workflow

The canonical loop is launch → wait → status → drive:

1. pbi_launch {pbip:"C:/path/to/Report.pbip"} — launches Desktop with the CDP debug port and waits until the port answers. The port only exists when Desktop is started with the right environment variable, and it cannot be attached later — so this must be how Desktop comes up.

2. pbi_wait_for {text:"<a page name>"} — the CDP port answering does not mean the canvas has finished rendering; a heavy report re-queries every visual for seconds-to-minutes. Poll for a known page/visual label to appear first.

3. pbi_status — confirm build, title bar, active page, page count, zoom, and canvasReady.

4. Drive it — pbi_pages, pbi_goto_page, pbi_set_slicer, pbi_read_cards, pbi_read_matrix, pbi_cross_filter_test, pbi_visuals, pbi_screenshot, …

If Desktop is already running on the port, pbi_launch reports the existing instance instead of starting a second one (a second instance competes for Analysis Services memory and makes both render as if frozen).

Environment variables

How pbi_launch resolves a launcher

pbi_launch tries three strategies in order and reports which one it used (launcher: "bridge-env" | "bridge-path" | "direct"):

1. PBI_DESKTOP_BRIDGE — the explicit bridge CLI path from the env var.

2. powerbi-desktop on PATH — resolved via where.exe (the npm-installed bridge CLI shim).

3. Direct PBIDesktop.exe spawn — needs no Microsoft CLI at all. Locates the exe from PBI_DESKTOP_EXE, then %ProgramFiles%\Microsoft Power BI Desktop\bin\PBIDesktop.exe, then the Store alias %LOCALAPPDATA%\Microsoft\WindowsApps\PBIDesktop.exe.

All three inject WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<port> into Desktop's own process environment (the only way the port gets enabled). If nothing resolves, pbi_launch returns {launched:false, error, hint} telling you to npm i -g @microsoft/powerbi-desktop-bridge-cli or set PBI_DESKTOP_EXE.

Tools

55 tools. Each returns a leading status key: the connected: family reports CDP reachability of the report canvas ({connected:false, ...} when Desktop is unreachable); the ok: family covers escape hatches, the separate DAX/TMDL/dialog CDP targets, and the guarded save/close/reload tools ({ok:false, reason} — or a {ok:true, <action>:false, reason} refusal — when a surface isn't available or a guard flag wasn't passed). Tools returning found:false / extracted:false also carry a structured code REASON (not-found / not-ready / wrong-view / canvas-busy / not-extractable) so a loop can branch on the failure without string-matching.

Dirty state is not detectable over CDP. Verified against Desktop 2.155: a real report edit changes nothing reachable from any WebView target (no title-bar change, no *, Save button always enabled, no window.powerbi.isDirty). Power BI Desktop's dirty flag lives in its native WPF host shell, which CDP cannot see. So pbi_save/pbi_close/ pbi_reload never detect unsaved work — they gate on your explicit intent flag (confirm / discardChanges / saveFirst). This is deliberate: a guard that silently under-reports "clean" would be more dangerous than one that always asks you to state intent.

Cost tiers

A loop should poll the CHEAP tools; call HEAVY tools only intentionally.

Choosing between similar tools

Several tools overlap in area but answer different questions — pick by intent:

• State reads: pbi_status (build/title/page/zoom) · pbi_state_probe (toggles/cards/badges/selection — cheapest data probe) · pbi_health (broken/console/heap quick-check) · pbi_page_digest (everything in one call — supersets state_probe; use it as the agentic observe step, state_probe when you only need the cheap scorecard).

• Slicers: pbi_set_slicer (one button/item) · pbi_multiselect_slicer (several list items, Ctrl-held) · pbi_search_slicer (type in the search box, optional pick). Distinct mechanics — not interchangeable.

• Grids: pbi_read_matrix (matrix/pivot, merges row headers) · pbi_read_table (flat tableEx, no row headers). pbi_show_as_table is the best-effort extractor for non-grid visuals (and often returns not-extractable — see below).

• Waiting: pbi_wait_for (a specific text appears/disappears) · pbi_wait_stable (render fully settles — deterministic, use after a nav/edit).

• Escape hatches: pbi_eval (page.evaluate, synthetic events — read-only DOM) · pbi_run_code (trusted page.mouse/page.keyboard — real input).

• Screenshots: pbi_screenshot (full page or one visual via visualTitle) · pbi_annotate_screenshot (numbered overlay boxes + legend for multimodal judging).

Model & DAX introspection

pbi_model_info gives you a metadata browser — measures, tables, columns, and relationships as structured rows — with no XMLA connection. It runs INFO.VIEW.* DAX (INFO.VIEW.MEASURES/TABLES/COLUMNS/RELATIONSHIPS()) inside the DAX query view and shapes the result grid, so you read the model over the same CDP channel as everything else.

• Precondition: the DAX query view must be OPEN in Desktop (the Home ribbon's "DAX query view" tab). These tools reach the separate daxQueryView CDP target and will not open ribbon views for you — same precondition as pbi_read_dax_editor.

• Filter with table (exact [Table]), nameLike (CONTAINSSTRING on [Name]), and top. The heavy Expression / FormatStringDefinition / DetailRowsDefinition columns are dropped by default; pass includeExpression:true to keep them.

• pbi_dax_batch runs up to 20 queries in one call; pbi_format_dax pretty-prints the editor via Monaco's Format Document action.

• Editor safety. pbi_dax_query / pbi_model_info / pbi_dax_batch overwrite the query editor, so they capture the prior text first and restore it (restore:true on dax_query, on by default for dax_batch, always for model_info). You can also snapshot and re-instate the buffer manually with pbi_editor_buffer {action:"capture"|"restore"}.

Reading visual data

Grids expose their full data in the DOM; charts do not. This asymmetry is the single most important thing to know when reading values:

• Matrices & tables (pbi_read_matrix, pbi_read_table) return the complete grid — every cell is a real DOM node, and both tools scroll virtualized grids and merge the rows. This is the reliable path for any tabular data.

• Chart values are NOT in the DOM. Verified against Desktop 2.155: donut/column/line visuals render their marks without persistent DOM values — arcs aren't addressable SVG paths, and the role="option" nodes carry aria-label="null" (only category labels are present as text). Scraping a chart's values from the DOM does not work.

• pbi_show_as_table is a best-effort extra path: it right-clicks a data point → "Show as a table" (or the Alt+Shift+F11 accessible show-data table), reads the overlay grid, and restores the canvas. It only works where the visual exposes a DOM data point — many chart/canvas/custom visuals expose none, so it honestly returns {extracted:false, code:"not-extractable"}. Prefer read_matrix / read_table for tabular data; reach for show_as_table only when the data lives behind a chart.

Agentic loop v2

The canonical safe act → observe → judge → verify loop. Every state-changing step is behind an explicit guard flag — the loop only passes confirm / saveFirst / discardChanges when the edit is legitimate, so a test-click loop can never persist garbage or lose work. The v1.2.0 tools collapse the observe/judge/verify steps into single round-trips:

• settle — pbi_wait_stable blocks until the render is actually done (LayoutCount / RecalcStyleCount flat + aria-busy clear), instead of guessing at a fixed timeout.

• observe — pbi_page_digest returns visuals + cards + badges + slicers + broken visuals + console errors in ONE call.

• judge — pbi_assert runs structured predicates (cardEquals, visualCountAtLeast, noBrokenVisuals, activePageIs) over a fresh digest and returns pass/fail.

• verify change — pbi_diff_state captures a digest before an action and structurally diffs it after (which cards changed, visual/broken deltas, slicer/page changes).

pbi_launch → pbi_wait_for
  → pbi_diff_state {action:"capture", name:"before"}   # snapshot the page digest
  → (edit via your model/authoring MCP)
  → pbi_reload {saveFirst:true, stable:true}           # repaint from the loaded model + wait for settle (guarded; no data refresh)
  → pbi_page_digest                                     # ONE-call observe: broken visuals? console errors? cards?
  → pbi_assert {noBrokenVisuals:true, cardEquals:{...}} # judge: did it land?
  → pbi_diff_state {action:"compare", name:"before"}    # verify: exactly what changed
  → judge → fix → repeat
  → (restore slicers/selection: pbi_deselect / CLEAR bookmark)
  → pbi_save {confirm:true}                             # opt-in save
  → pbi_close {discardChanges:true}                     # deliberate teardown at the very end (flag always required)

Between iterations, observe with pbi_page_digest / pbi_health and pbi_status {light:true} (all CHEAP). Restore slicers/selection BEFORE pbi_save {confirm:true} so you don't persist test-click state. pbi_save, pbi_close, and pbi_reload NEVER act without their guard flag — without it they return a refusal object, not the action.

Robustness

Newer tools resolve elements through an ARIA-role resolver (role + accessible name) rather than brittle class selectors, so they survive Desktop DOM churn better. When a tool can't complete, it returns a structured REASON code instead of a bare error, so a loop can branch on the failure kind without string-matching:

Safety & etiquette

Every interaction happens against the live, unsaved report in memory. Follow these:

• Never save after test clicks. Every click mutates unsaved in-memory report state. Restore slicers / active page when done (a CLEAR bookmark or pbi_deselect helps; the sweep/baseline/bookmark tools restore the starting page/chrome for you).

• pbi_dialog refuses to click a Save button unless button is passed exactly as "Save" (case-sensitive) — a guard against accidentally saving the report.

• Token guard is honest, not a sandbox. pbi_eval and pbi_run_code reject code that references powerBIAccessToken, but that is a best-effort textual (regex) guard, not a security sandbox. Do not rely on it as a boundary.

• Restore state after test clicks so the next run starts clean.

• Screenshots and baselines are written to PBI_OUTPUT_DIR (a temp dir), never the repo.

Troubleshooting

• {connected:false} from every tool — Desktop isn't reachable on the CDP port. Launch via pbi_launch (the port is enabled only at launch and cannot be attached later). Verify with Invoke-RestMethod http://127.0.0.1:9222/json/version.

• Use 127.0.0.1, never localhost — localhost resolves IPv6 first and times out; the debug port binds IPv4 loopback only.

• renderer-busy errors — a page.evaluate landed while the canvas was mid-render (page switch or visual queries in flight). The read fails fast rather than hanging; retry in a few seconds, or use pbi_wait_for to gate on readiness.

• Report renders as if frozen / blank — check pbi_launch's pre-flight warnings. Orphaned msmdsrv (Analysis Services) engines from earlier debug launches hold RAM and starve the new instance; end the msmdsrv processes with no matching Desktop (or reboot) before blaming the report. Also avoid two Desktop instances at once.

• A selector stopped matching after a Desktop update — use pbi_snapshot (ARIA tree) or pbi_deep_snapshot to rediscover structure, then pbi_run_code to drive it.

Coexistence with other CDP clients

CDP supports multiple simultaneous clients attached to the same endpoint. So pbi-webview2 can run alongside any other CDP client (Playwright, another MCP server, a DevTools window) pointed at http://127.0.0.1:9222 at the same time — they don't conflict. On disconnect, pbi-webview2 never closes Desktop: connectOverCDP's close only detaches the CDP session, it doesn't terminate the process.

Development / test

npm test   # smoke test — passes WITHOUT Desktop running (asserts connected:false)

The smoke test spawns node server.js, speaks MCP over stdio, asserts all 55 tools are registered (exact-count assertion), then calls pbi_status and asserts it returns {connected:false, error, hint} (Desktop not running). It points the CDP endpoint at a dead port so the connect fails fast — no Desktop required.

License

MIT — see LICENSE.