pbidriver
WebDriver for Power BI Desktop, so AI agents can see and drive the reports they edit.
Agents can already write DAX and edit PBIP files, but they cannot see the result. pbidriver gives them pixel-exact captures, the numbers behind every visual, slicers, menus, dialogs, DAX and Performance Analyzer timings, from a CLI that prints one JSON object per call.
pip install pbidrivernpx pbidriver> pbidriver shot --page "Overview" --annotate
{"ok": true, "file": "pbidriver_shots/...png",
"alerts": {"blocked": false}, ...}
> pbidriver read --visual 4
{"ok": true, "points": [...], ...}
> pbidriver slicer --visual 5 --select "West"
{"ok": true, ...}
> ▍
- commands, each printing one JSON object
- 25commands, each printing one JSON object
- views it can capture, from the canvas to TMDL
- 5views it can capture, from the canvas to TMDL
- dialog technologies it detects and answers
- 3dialog technologies it detects and answers
- agents with setup guides, Claude Code to Cursor
- 4agents with setup guides, Claude Code to Cursor
The gap it closes
Coding agents can write DAX and edit the files of a PBIP project. What they cannot do is look at the report afterwards. A screenshot of the whole desktop is noisy and needs the window in focus, and publishing to the Power BI service to check each change breaks the fast loop of edit, look, fix.
pbidriver runs locally against Power BI Desktop. Every command is a CLI call that prints one JSON object, so any agent that can run a shell command can use it: Claude Code, Codex, GitHub Copilot, Cursor or a script of your own.
The name means “driver” as in WebDriver, the thing that drives an app for automation. It is not a data connector or an ODBC driver.
A short session
pbidriver launch "C:\reports\Sales.pbix"
pbidriver shot --page "Overview" --annotate
pbidriver read --page "Overview"
pbidriver slicer --visual "Region" --select "West" --shot
pbidriver dax "EVALUATE TOPN(5, Sales)"
shot --annotate saves a PNG of the canvas with each visual’s index drawn on it, so the agent can refer to “visual 18” in its next command. read returns chart points, card values, table cells and slicer state. Each call prints one JSON object, and any call that touches the UI also reports alerts, such as a dialog blocking the window.
Two ways to connect
Started with pbidriver launch |
Any open Power BI Desktop | |
|---|---|---|
| How | DevTools on a private WebView2 profile, so it runs next to your other Power BI windows | Microsoft’s Desktop Bridge, the local model engine and Windows itself |
| Page and visual captures | Live state, any zoom, every view | Report pages and visuals |
| Read visuals, slicers, clicks, menus | Yes | No |
| Dialogs | All three kinds | Native and legacy ones |
| Inventory, DAX, model, reload, status | Yes | Yes |
pbidriver instances lists every running Power BI Desktop with its process ID, file, DevTools port and Bridge status, and --pid picks one. It works with both the Microsoft Store and the installer builds of Power BI Desktop, and needs Python 3.9 or later.
What an agent can do with it
| Verb | What it covers |
|---|---|
| See | Pixel-exact PNGs of the canvas, one visual, every visual, the whole UI, or the Table, Model, DAX query and TMDL views. Works when the canvas is larger than the window, when the window is minimized and when it sits behind others. |
| Read | Chart data points, cards, tables and matrices (virtualized grids are scrolled through), slicer options and their selection, all formatted the way Power BI formats them. |
| Stay unblocked | Blocking dialogs are detected on every call, then read, captured and answered with dialog --click. Input is refused while a modal is open. Broken visuals are reported. |
| Interact | Real mouse and keyboard input: slicers, clicks, scrolling (sideways too, in wide tables), typing, tooltips, context and “More options” menus, bookmarks. |
| Understand | Every page, visual, field, filter and bookmark from the report file, plus the model’s tables, columns, measures with their DAX, and relationships. |
| Measure | Performance Analyzer timings per visual, split into DAX query, visual display and other, optionally with each visual’s query. |
| Close the loop | Reload a PBIP after edits on disk, save, and close while answering the save prompt. |
How it works
- DevTools. Power BI Desktop draws its interface in WebView2, one Chromium page per view.
launchstarts an instance with a private WebView2 profile and a remote debugging port, which gives it its own browser process, so it works next to your other Power BI windows. pbidriver attaches with Playwright over the Chrome DevTools Protocol. - Pixel-exact captures. Only the target’s rectangle is captured, so panes and scrollbars never leak in. If the canvas does not fit the window, the viewport is emulated larger for the capture and then restored. A minimized window is restored without taking focus and put back exactly as it was.
- Data. Built-in visuals bind each data point to its element along with tooltip info, so values come out exactly as Power BI shows them. Tables and matrices are read cell by cell through their ARIA grid roles.
- Dialogs. Power BI uses three technologies. In-app dialogs are read from the DOM. Native WinForms dialogs are read from their child windows and clicked with
BM_CLICK. Legacy Internet Explorer dialogs, such as the “save your changes?” prompt, are read and clicked through their own HTML viaWM_HTML_GETOBJECT. - DAX. Windows PowerShell loads the ADOMD.NET client that ships inside Power BI Desktop and queries the local model engine. Nothing extra is installed.
- Desktop Bridge. On Power BI Desktop from June 2026, Microsoft’s local JSON-RPC API provides page snapshots, reloads and unsaved state for any open window, including ones pbidriver did not launch.
From Node.js
The pbidriver npm package runs the same CLI from Node, for JavaScript projects and agents that reach for npx first:
npx pbidriver shot --page "Overview" --annotate
It finds the Python side on its own: an interpreter named in PBIDRIVER_PYTHON, else uvx (which downloads and caches the matching version on first use), else Python 3.9+ on the path, installing the matching version once with pip. Installer output goes to stderr, so stdout stays a single JSON object. There is a typed JavaScript API as well:
const { run } = require('pbidriver');
const shot = await run(['shot', '--page', 'Overview', '--annotate']);
if (shot.ok) console.log('PNG at', shot.file);
Power BI’s internals are reached through Windows APIs that Python handles well, so the npm package starts the Python CLI rather than reimplementing it. Both packages ship together from the same release, and a test checks that their version numbers match.
Drop-in instructions for agents
The README includes a block to paste into CLAUDE.md or AGENTS.md. It tells the agent how to start, look, read numbers, deal with alerts and dialogs, reload after editing PBIP files and finish cleanly. The documentation site has setup pages for Claude Code, GitHub Copilot, Codex and Cursor.
Limits, written down
- The DOM selectors are Power BI internals. They are tested on Power BI Desktop 2.152 (March 2026) and 2.159 (November 2026). A monthly update can rename them, so they are grouped in one place.
- Custom visuals render in sandboxed iframes. They can be captured and clicked, but their data cannot be read; use
daxwith the fields frominventoryinstead. perfandbookmarkslook for English ribbon labels.launchopens a DevTools port on127.0.0.1. While that instance runs, any program on the machine could drive it, including your signed-in Power BI session. Close it when you are done.
Questions
- Can an AI agent see a Power BI Desktop report?
- Yes, with pbidriver. pbidriver shot saves a pixel-exact PNG of a report page, one visual or every view, and pbidriver read returns the values behind the visuals as JSON. Neither needs the Power BI service or a screenshot of the whole desktop.
- Does pbidriver need the Power BI service, a Pro licence or publishing?
- No. It works entirely against Power BI Desktop on your own Windows machine. Nothing is uploaded or published.
- Does it work with Claude Code, GitHub Copilot, Codex or Cursor?
- Yes. It is a command-line tool that prints JSON, so any agent that can run shell commands can use it. The documentation has setup pages for each, and no MCP server or plugin is needed.
- How is it different from Microsoft's Power BI Desktop Bridge?
- The Desktop Bridge reports the open file, reloads PBIP projects and captures report pages. pbidriver uses it where it helps and adds reading visual data, slicers, clicks and menus, captures of the Table, Model, DAX query and TMDL views, dialog handling, DAX queries and Performance Analyzer timings. It also works on builds older than the Bridge.
- Is there an npm package?
- Yes. npx pbidriver runs the same CLI from Node.js through uv or Python 3.9+, and require('pbidriver').run([...]) resolves with each command's JSON result.
- Does it work on macOS or Linux?
- No. Power BI Desktop only runs on Windows, so pbidriver needs Windows 10 or 11.
Further reading
- Use with AI agents: setup for Claude Code, Copilot, Codex and Cursor, with six recipes
- Command reference
- How it works
- FAQ: including how it compares with the Desktop Bridge and the Modeling MCP server