powerbi-plus

An MCP server for building and inspecting Power BI report visuals by editing the report's PBIR files on disk. It complements the model-layer MCPs (XMLA/TOM) by owning the layer they can't reach: pages, charts, slicers, cards, layout.

Why two layers

Power BI automates in two very different ways:

Layer	What	How reached
Semantic model	tables, columns, measures, relationships, DAX	live via the Analysis Services / XMLA endpoint while Desktop is open
Report / visuals	pages, charts, slicers, layout, formatting	file-based — no live canvas API

This server is the report layer. It reads and edits the per-visual JSON files of a report saved in PBIR format. Changes land on disk; Power BI Desktop picks them up when the project is reopened/reloaded — there is no supported way to draw on a live session's canvas.

Prerequisite: save your report as PBIP with PBIR format

A classic .pbix stores the report as an opaque blob this server can't safely edit. One-time conversion in Power BI Desktop:

1. File → Options and settings → Options → Preview features — enable:
   • Power BI Project (.pbip) save option
   • Store reports using enhanced metadata format (PBIR)
2. Restart Desktop if prompted.
3. File → Save as → Power BI project (.pbip).

You get a folder tree:

<Project>.pbip
<Project>.Report/
  definition.pbir
  definition/
    report.json
    pages/
      pages.json
      <pageName>/
        page.json
        visuals/
          <visualName>/visual.json   ← one file per visual
<Project>.SemanticModel/

open_project reports the format; if it says anything other than PBIR, finish the conversion above before inspecting/editing.

Install

cd C:\path\to\mcp-powerbi-plus
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Register the server

Add the entry below to your MCP config, fixing the two paths to point at this checkout's .venv python and server.py. Use double backslashes in JSON on Windows, and write the file as UTF-8 without a BOM (a BOM breaks the JSON parser). Restart the client afterward — MCP servers load at launch.

{
  "mcpServers": {
    "powerbi-plus": {
      "command": "C:\\path\\to\\mcp-powerbi-plus\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\mcp-powerbi-plus\\server.py"
      ]
    }
  }
}

Where the config lives, by client:

Client	Config file	Notes
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)	Merge powerbi-plus into the top-level mcpServers. Fully quit and relaunch the app (closing the window isn't enough — use File → Exit / the tray icon).
Claude Code	~/.claude.json	Add to the top-level mcpServers, or run claude mcp add. Restart the CLI session.

A ready-to-edit snippet is in examples/mcp.json. Once registered, the tools appear as powerbi-plus's tools (e.g. mcp__powerbi-plus__open_project).

Config (config.json)

Pure filesystem — no Azure auth.

Key	Meaning
writable	gates future create/update/delete/theme tools. Read/inspect always work.
default_project	optional path used when a tool's project arg is omitted; a .pbip file or *.Report folder.

Tools — read / inspect

Tool	Does
open_project	format (PBIR vs legacy blob), name, dataset pointer, theme, page count, active page
list_pages	pages in order: internal name, displayName, size, visual count, active flag
inspect_page	visuals on a page: name, type, title, position, bound roles
inspect_visual	one visual in full: type, title, position, field bindings per role, formatting objects, filters
list_model_fields	tables / columns (+dataType) / measures from the sibling *.SemanticModel — use as binding entity/property

Tools — write (gated by "writable": true)

Tool	Does
add_visual	create a visual on a page (type + field bindings + position + title)
update_visual	edit an existing visual in place (type / bindings / title / position)
move_visual	reposition / resize (x / y / width / height / z)
delete_visual	remove a visual
add_page	create a page and register it in pages.json
delete_page	remove a page + its visuals, reassign active page
generate_page	create a page and auto-lay-out a list of visuals on a column grid in one call
format_visual	set formatting on a visual (background, title, legend, dataColors…), merging into existing objects
apply_theme	apply a custom report theme — update an existing registered theme in place, or stage a new one

project is accepted on every tool and may be a .pbip file, the *.Report folder, the definition folder, or a parent dir holding one *.Report. Omit it to use default_project.

Binding shape

bindings maps a visual role to one field spec or a list of them:

{
  "Category": { "entity": "DimRegion", "property": "Region" },          // column (default)
  "Y":        { "entity": "FactSales", "property": "Total Sales", "kind": "measure" },
  "Values":   { "entity": "FactSales", "property": "Amount", "aggregation": "sum" }  // wraps a column
}

Roles by visual: chart → Category + Y; card → Values; matrix (pivotTable) → Rows + Columns + Values; slicer → Values. aggregation ∈ sum / avg / min / max / count / countNonNull / median / stdev / var.

Edits land on disk. Close the report in Power BI Desktop before writing, then reopen the project to see changes — there is no live-canvas push.

generate_page layout

Items flow left-to-right across a column grid (default 12 cols) and wrap to a new row when full; a row's height is its tallest item. Per item: colSpan (grid width, default half), height (points). An item with an explicit position is pinned and skips the flow. Optional layout overrides {columns, margin, gutter, rowHeight}. The whole spec is validated and built in memory before the page is created — an invalid spec writes nothing.

format_visual value encoding

formatting is {object: {prop: value}}. Values auto-encode to PBIR property expressions: bool → true/false, int → whole-number literal (14L), float → decimal (50.5D), "#RRGGBB" or a color-named prop → solid color, other text → quoted string. Force a type with {"type":"color|text|int|number|bool","value":…} or pass a ready node with {"raw": {…}}. target auto-routes container objects (title/background/border/shadow/…) to visualContainerObjects and the rest to objects; override with "objects" / "container".

apply_theme — what's actually supported

PBIR is in preview, and registering a brand-new resource by external edit is not supported (it needs a report.json change Desktop owns). So:

• Theme already registered → apply_theme overwrites it (or deep-merges with merge: true). Reopen Desktop to load. ✅ supported.
• No theme registered yet → the file is staged under StaticResources/RegisteredResources; register it once via Desktop View → Themes → Browse for themes, after which updates work in place. The returned supported flag tells you which path ran.

list_model_fields

Reads the report's semantic model (resolved via definition.pbir byPath, or a single sibling *.SemanticModel) and returns its tables, columns (with dataType), and measures — so you can bind visuals to fields that actually exist. TMDL and legacy model.bim/TMSL are both parsed; hidden fields are excluded unless include_hidden: true. Reports on a live (byConnection) dataset have no local model files — query those via the powerbi-modeling or powerbi MCP instead.

Status

All 14 tools are verified against a synthetic PBIR fixture (every write round-trips through the read layer). Not yet validated against a report opened in Power BI Desktop — schema details like literal suffixes (L/D), the title bucket, and theme registration should be confirmed on a real .pbip before relying on the write tools in production.

License

MIT.