powerbi-plus

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)

1. Restart Desktop if prompted.
2. 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.