pbi-mcp

MCP servers for local-file Power BI Project (.pbip) automation — model (TMDL) and report (PBIR) layers. No Power BI API, no auth, no cloud: the tools read and write the on-disk project files Power BI Desktop itself uses.

Build a correctly-bound, themed, filtered, multi-page report — or bulk-author hundreds of measures — from a prompt, in minutes. 56 tools across two MCP servers; every report write is pre-flight validated against the official Fabric schemas.

Fastest path: pbi_set_project(path) → pbi_scaffold_report() profiles the model and builds a themed, navigable, multi-page designed report in one call (use dry_run=true to review the proposal first). Or compose it yourself with pbi_build_designed_page, the design elements, and the theme generator.

Scope honesty. This builds structure, speed, consistency. It does not do custom Deneb/Vega visuals, AppSource visual sourcing, or replace design taste. It's a fast report builder, not an autonomous report designer.

Safety model (the part that matters)

The one unforgivable bug for a tool like this is producing a project Desktop refuses to open. Every mutation therefore goes through:

• atomic writes (temp file + rename — a crash never leaves a half file)

• backup-once-per-file snapshots (*.bak-<timestamp>), with pbi_list_backups / pbi_restore_backup to recover

• surgical text edits for TMDL — the parsed model is never re-emitted, so partitions, annotations, and M source are preserved byte-for-byte

• style preservation — each file keeps its exact line endings + BOM (Desktop mixes CRLF and LF across file types)

• deletion fail-safes — deleting a measure that other measures, visuals, or filters depend on is refused (transitive DAX lineage + report usage); force=true overrides, dry_run=true previews

• recoverable visual deletes — removed visuals move to Report/.pbi/mcp-trash/, which Desktop ignores

Download the plugin

For the easiest install, download one of the bundles from dist/:

• pbi-mcp-standalone-win32-amd64.plugin - self-contained Windows build; no local Python setup required.

• pbi-mcp.plugin - source plugin bundle; requires Python 3.11+ and the package dependencies on the host.

Drag the .plugin file into a plugin-aware MCP host, then call pbi_set_project(path) first in both pbi-model and pbi-report sessions.

Quickstart

git clone <repo> && cd pbi-mcp
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
.venv\Scripts\python -m pytest          # green suite = good to go

Register in Claude Desktop: run scripts/package.py, then merge dist/claude_desktop_config.snippet.json into your claude_desktop_config.json and restart. Or drag-drop dist/pbi-mcp.plugin into a plugin-aware host. Details: INSTALL.md inside the bundle.

Every session starts with pbi_set_project(path) — point it at a .pbip saved with Desktop's PBIP preview format (enable Power BI Project (.pbip) save option + PBIR enhanced metadata in Options → Preview features).

Tool reference

pbi-model server (semantic model / TMDL)

pbi-report server (report / PBIR)

pbi-report — design, intelligence & lifecycle (v2)

Binding format

Bindings are {bucket: ["Table.Field", ...]}. Measures vs columns are resolved automatically. Bucket names are per-visual-type and validated from core/visual_specs.py, whose contents were surveyed from real Desktop exports (150+ visuals) — notably: the Legend bucket is Series, combo charts use Y + Y2, donut charts have no Category.

// a bar chart spec for pbi_add_visual / pbi_build_page
{
  "visual_type": "clusteredBarChart",
  "bindings": {"Category": ["Date.Year"], "Y": ["Sales.Net Revenue"]},
  "title": "Revenue by Year",
  "position": {"x": 40, "y": 40, "width": 600, "height": 360}  // optional
}

Layout

pbi-mcp/
  core/            # PbipProject + TMDL/PBIR read-write, specs, lineage,
                   # usage classifier, formatting/filter builders, safe I/O
  model_server/    # MCP server: pbi-model
  report_server/   # MCP server: pbi-report
  scripts/         # smoke test, M5 demo, packager
  tests/           # 220+ tests; fixtures/ (synthetic + real, gitignored)

Testing

Fixture-based + golden files + fuzz. The suite runs against a synthetic PBIP project (committed) and any real exports dropped under tests/fixtures/real/ (auto-discovered, never committed). Golden snapshots of emitted visual.json live in tests/goldens/ (regenerate deliberately with PBI_MCP_REGEN_GOLDENS=1). A seeded 60-op fuzz storm asserts the project always reloads parseable. The reopen-in-Desktop check stays a manual gate before each release.

License

MIT.