pbi-mcp
Summary: This is the pbi-model MCP server, which reads and writes the semantic model (TMDL) layer of a local Power BI Project (.pbip) file — no Power BI API, auth, or cloud required.
Session setup —
pbi_set_project(path)points the server at a.pbip; every session must start here.Inspect the model —
pbi_get_model()returns tables, columns, measures, and relationships;pbi_list_measures(table?)lists measures with DAX and format strings;pbi_model_lineage(measure?)gives a DAX dependency graph with direct/transitive dependents.Author measures —
pbi_create_measure(table, name, dax, format?, display_folder?)creates one (name must be unique model-wide);pbi_update_measure(...)does partial updates keeping omitted fields;pbi_bulk_create_measures(measures)batch-creates with full-batch validation before any write.Delete safely —
pbi_delete_measure(table, name, force?, dry_run?)refuses deletion if other measures or the report depend on it unlessforce=true, anddry_run=truepreviews without writing.Author columns & relationships —
pbi_create_column(table, name, data_type, summarize_by?, source_column?, dax?)for data or calculated columns;pbi_create_relationship(from_table, from_column, to_table, to_column, cardinality?, cross_filter?, is_active?)with endpoint validation and duplicate detection.Calculation groups —
pbi_create_calc_group(name, precedence, items)builds a full calc-group table plus itsmodel.tmdlregistration.Backup & recovery —
pbi_list_backups()lists.bak-*snapshots newest-first;pbi_restore_backup(backup)restores one over its original file.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pbi-mcp scaffold a multi-page report from the sales project model"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pbi-mcp
MCP servers for local-file Power BI Project (.pbip) automation — model
(TMDL) and report (PBIR) layers. The model and report servers use no Power BI
API, no auth and no cloud: the tools read and write the on-disk project files
Power BI Desktop itself uses. Two optional extras go further: a live engine
connection to a running Desktop, and a pbi-service server for the Fabric
REST APIs.
Build a correctly-bound, themed, filtered, multi-page report — or bulk-author hundreds of measures — from a prompt, in minutes. 154 tools (73 model + 81 report) 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 ships Deneb (Vega-Lite) templates, but it does not source AppSource visuals or replace design taste. It's a fast report builder, not an autonomous report designer. Shapes the vendored schemas leave open (conditional-format icons, analytics lines, field parameters, KPIs) follow Desktop exports and the docs but have not all been reopened in Desktop; the reopen check stays a manual gate, and each such tool says what is unconfirmed.
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>), withpbi_list_backups/pbi_restore_backupto recoversurgical 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=trueoverrides,dry_run=truepreviewsrecoverable visual deletes — removed visuals move to
Report/.pbi/mcp-trash/, which Desktop ignoresdry_run=trueon write tools — the call runs against a scratch copy and returns a unified diff; nothing is writtenundo journal and transactions — real writes keep byte-exact pre-images under
<project>/.pbi-mcp/undo/;pbi_undoreverts them, andpbi_begin_transaction/pbi_commit/pbi_rollbackgroup several writes (restore, cloud and render tools have no preview)tool annotations — every tool declares read-only / destructive / idempotent hints, so hosts can auto-approve reads and gate deletes
Related MCP server: superbi-mcp
Install
Pick one option. Whichever you choose, your MCP host launches the two servers
(model for the semantic model, report for the report layer), and every
session starts with pbi_set_project(path).
A. From PyPI: uvx or pip (recommended)
Needs Python 3.11+, or uv, which fetches Python for you.
uvx pbi-mcp report # run once, nothing to install
pip install pbi-mcp # or install; gives you the `pbi-mcp` command
pbi-mcp model # model | report | service, stdio by default
pbi-mcp report --transport streamable-http --port 8000 # HTTP on 127.0.0.1--project PATH (or the PBI_MCP_PROJECT environment variable) preselects a
.pbip at startup. The HTTP transports have no authentication, so keep the
default --host 127.0.0.1.
Claude Desktop: Settings > Developer > Edit Config, add the following to
claude_desktop_config.json, then restart.
{
"mcpServers": {
"pbi-model": { "command": "uvx", "args": ["pbi-mcp", "model"] },
"pbi-report": { "command": "uvx", "args": ["pbi-mcp", "report"] }
}
}Claude Code:
claude mcp add pbi-model -- uvx pbi-mcp model
claude mcp add pbi-report -- uvx pbi-mcp reportAdd --scope project to write a shared .mcp.json in your repository instead;
its content is the same mcpServers JSON as above.
Cursor: put the same mcpServers JSON in ~/.cursor/mcp.json (all
projects) or .cursor/mcp.json (one project).
VS Code: .vscode/mcp.json uses a servers key and an explicit type:
{
"servers": {
"pbi-model": { "type": "stdio", "command": "uvx", "args": ["pbi-mcp", "model"] },
"pbi-report": { "type": "stdio", "command": "uvx", "args": ["pbi-mcp", "report"] }
}
}Installed with pip instead of uvx? Use "command": "pbi-mcp" with
"args": ["report"] (or ["model"]) in any of the snippets above.
B. Standalone .plugin bundle (no Python needed)
Download from the latest GitHub Release:
pbi-mcp-standalone-win32-amd64.plugin,pbi-mcp-standalone-darwin-arm64.pluginorpbi-mcp-standalone-linux-x86_64.plugin: a self-contained build for that platform (Python runtime, dependencies and schemas inside); no local setup.pbi-mcp.plugin: the source plugin bundle; requires Python 3.11+ plusmcp(1.x or 2.x),pydanticandjsonschemaon the host.
Drag the .plugin file into a plugin-aware MCP host. The standalone builds are
~25 MB, published only as release assets (not tracked in git), and listed with
checksums in SHA256SUMS.txt; rebuild one locally with
scripts/build_standalone.py.
C. .mcpb for Claude Desktop
Each release also carries one MCP Bundle per server, pbi-mcp-model.mcpb and
pbi-mcp-report.mcpb. Open one in Claude Desktop (double-click, or Settings >
Extensions) and optionally choose a default project folder. These bundles use
the machine's Python, so it needs Python 3.11+ with
pip install "mcp<3" pydantic jsonschema; options A and B avoid that.
D. From source
git clone https://github.com/rajdeepraoextras-dev/PBI-MCP-Server.git && cd PBI-MCP-Server
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]" # macOS/Linux: .venv/bin/pip
.venv\Scripts\python -m pytest # green suite = good to go
.venv\Scripts\python -m core.cli report # or: python -m report_server.serverBuild the distributables yourself with python scripts/package.py (writes
dist/pbi-mcp.plugin, dist/*.mcpb and dist/claude_desktop_config.snippet.json,
whose paths point at your checkout). See
CONTRIBUTING.md
to contribute and
CHANGELOG.md
for what changed.
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)
Tool | What it does |
| Select the project; returns table/measure counts |
| Tables, columns, measures, relationships snapshot |
| Measures with DAX + format string |
| DAX dependency graph; per-measure deps + direct/transitive dependents |
| Create (name must be unique model-wide) |
| Partial update; omitted fields kept |
| Delete with lineage + report-usage guards |
| Data column, or calculated column with |
| Endpoints validated; duplicates detected |
| Full calc-group table + model.tmdl registration |
| Batch create; whole batch validated before any write |
| Recovery |
pbi-report server (report / PBIR)
Tool | What it does |
| Select the project; returns page/visual counts |
| Pages: id, name, size, visual count, hidden |
| Visuals with type, position, title, bindings |
| Full config incl. raw visual.json |
| Classify every field direct / indirect / unused — the deletion fail-safe |
| New page, registered in pages.json |
| Batch add; buckets + model refs validated before any write |
| One call: page + visuals + auto-layout (KPI row, 2-col grid) |
| Rebind; formatting/position preserved |
| Partial move/resize |
| Recoverable delete (→ .pbi/mcp-trash) |
|
|
| Install + activate a standard PBI theme JSON |
| Categorical / Advanced / TopN / RelativeDate at report, page, or visual scope |
pbi-report — design, intelligence & lifecycle (v2)
Tool | What it does |
| Machine-readable spec: visual types, buckets, filters, examples |
| Autopilot: profile the model → themed multi-page designed report (dry_run to review) |
| Classify fact/dimension/date tables, measure roles, grouping columns |
| Header band + KPI strip on backplates + chart grid, one call |
| Brand color → coherent theme (palette, text classes, light/dark) |
| Design elements: titles, logos, backplates, dividers |
| Canvas background + wallpaper |
| Group as one block; raw escape hatch for any visual |
| Sort; page-navigation buttons |
| Drillthrough/tooltip pages; cross-filter control |
| Capture page + filter state |
| Page lifecycle (delete is recoverable) |
| Filter + trash management |
| Schema validation + design lint |
| Diff vs another project/backup; overview |
More tool families (v2.1)
The full, generated reference for every tool is in docs/tools/
(model.md, report.md, service.md).
Family | Tools |
Safety net |
|
Cascading rename |
|
Tables and queries |
|
Columns, hierarchies, KPIs |
|
Security and metadata | roles and OLS ( |
Quality |
|
Live engine |
|
Visual formatting |
|
Report measures, mobile, accessibility |
|
Rendering and Deneb |
|
Diff and import |
|
MCP resources (pbip://model, pbip://pages, ...) and prompts (audit_model,
bulk_measures, build_dashboard, theme_report, review_page) are also
registered.
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
}Cloud: pbi-service (optional)
A third MCP server, pbi-service, talks to the Power BI / Fabric REST APIs so
the project you built locally can be published, refreshed, promoted and
exported without leaving the session. It is strictly additive: pbi-model
and pbi-report never import it and keep working offline with no auth.
pip install -e ".[dev,cloud]" # cloud = msal, only needed for (c)/(d) below
python -m service_server.server # or: pbi-service-server / scripts/launcher.py serviceAuth is resolved in this order (first configured source wins; check
pbi_service_status()):
a token passed to
pbi_service_login(token=...)(session only)env
PBI_ACCESS_TOKEN(e.g. fromaz account get-access-token --resource https://analysis.windows.net/powerbi/api)a service principal from
AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET(msal, cached in memory, refreshed before expiry)interactive device code via
pbi_service_login(device_code=True)— requires envPBI_CLIENT_ID, the id of a public client app you register yourself (no client id is hard-coded); the first call returnsuser_code+verification_uri, a later call completes the sign-in
Tokens never touch disk or logs and every tool result is redacted.
Tool | What it does |
| Active auth source + identity hints, base URLs, last operation ids |
| Store a session token or start/poll a device-code sign-in |
| Select the local |
| Browse; workspaces/items accept an id or display name |
| Download a SemanticModel (TMDL) or Report (PBIR) into a PBIP-shaped folder the local servers can open |
| Upload the model (every file except |
| Trigger a refresh, optionally wait; recent history |
| Deploy all or selected items from a stage |
| Export to file and download it |
Cloud writes change nothing on disk, so they have no dry_run preview and
no pbi_undo; the service is the source of truth for them. HTTP goes
through stdlib urllib with retries on 429/5xx (honouring Retry-After) and
long-running operations polled with a timeout. The REST calls follow the
official Fabric Core Items and Power BI REST references but are exercised in
this repo only against scripted fakes — treat the first run against a real
tenant as a smoke test.
Layout
pbi-mcp/
core/ # PbipProject + TMDL/PBIR read-write, specs, lineage,
# usage classifier, formatting/filter builders, safe I/O;
# auth.py + fabric_api.py back the optional cloud server
model_server/ # MCP server: pbi-model
report_server/ # MCP server: pbi-report
service_server/ # MCP server: pbi-service (optional, cloud)
scripts/ # smoke test, M5 demo, packager
tests/ # 1700 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.
Live engine (optional)
Everything above works on the project files. On Windows with Power BI
Desktop installed, the pbi-model server also exposes read-only tools that
talk to the running model -- the local Analysis Services instance behind
an open Desktop window -- so DAX can be checked against real data before it
is written to TMDL. They never modify the project.
Tool | What it does |
| ADOMD DLL in use, running Desktop instances (port, databases, tables), the instance matched to the selected project, or why nothing is reachable. Never raises. |
| Run |
| The engine compiles a measure expression ( |
| Row count per table (storage DMV, |
| VertiPaq cardinality, dictionary / data / hierarchy size and encoding per column, largest first |
|
|
| Pin a remote XMLA endpoint (e.g. |
How it works (core/engine.py, no pip dependencies): each Desktop instance
writes its port to AnalysisServicesWorkspace_<guid>/Data/msmdsrv.port.txt.
Those folders are searched under %USERPROFILE%\Microsoft\Power BI Desktop Store App\AnalysisServicesWorkspaces (Store build), its package-virtualised
LocalCache twin, and %LOCALAPPDATA%\Microsoft\Power BI Desktop\... (MSI
build); only the port file is ever read. A port must accept a TCP connect
to count, and the instance is matched to the selected project by table
names. Queries run through ADOMD.NET in a spawned powershell.exe that
Add-Types the AdomdClient DLL shipped with Desktop (about 2 s per tool
call); query text and connection strings travel in a temp file, never on the
command line. The DLL is looked up as PBI_ADOMD_DLL (env), then the MSI
install, then the Store package (Get-AppxPackage, newest version). When
nothing is reachable the tools raise a clear EngineUnavailable ("open the
project in Power BI Desktop" / "set PBI_ADOMD_DLL"); on non-Windows they
always do.
A .pbip opens in Desktop without data: row counts are 0 and measures are
blank until the model is refreshed (the banner's Refresh now).
tests/fixtures/engine/Engine.pbip is a tiny project with inline data (three
Table.FromRows partitions, one relationship, three measures, one card) that
opens and refreshes in Desktop without any external source or credentials.
python scripts/desktop_launch.py tests/fixtures/engine/Engine.pbip --refresh # open + load data
python -m pytest tests/test_engine.py -q # the live tests run when an instance is up, else skip
python scripts/desktop_launch.py --close # normal close, answers "Don't save"; Stop-Process lastLicense
MIT.
Available Tools
13 toolspbi_bulk_create_measuresA
Create many measures at once. measures: [{"table","name","dax", "format"?,"display_folder"?}, ...]. The whole batch is validated before any write happens.
Inputs: measures (required).
pbi_create_calc_groupA
Create a calculation group table. items: [{"name","dax"}, ...] using SELECTEDMEASURE() patterns; order becomes the display order.
Inputs: name (required), items (required), precedence (required).
pbi_create_columnB
Create a column in table. Pass dax for a calculated column;
otherwise source_column defaults to the column name.
Inputs: name (required), table (required), data_type (required), dax, +2 more.
pbi_create_measureC
Create a measure in table. Fails if the measure name already exists.
Inputs: dax (required), name (required), table (required), format, +1 more.
pbi_create_relationshipB
Create a relationship (many-to-one from -> to by default). Both endpoint columns must already exist.
Inputs: to_table (required), to_column (required), from_table (required), from_column (required), +3 more.
pbi_delete_measureA
Delete a measure. Refuses if other measures OR the report depend on it unless force=true. dry_run=true previews without writing.
Inputs: name (required), table (required), force, dry_run.
pbi_get_modelB
Return tables, columns, measures, and relationships for the project.
Inputs: no named parameters.
pbi_list_backupsA
List every .bak-* snapshot the server has written, newest first.
Inputs: no named parameters. Returns: result
pbi_list_measuresA
List measures with DAX and format; optionally filter to one table.
Inputs: table. Returns: result
pbi_model_lineageA
Dependency graph (who references whom). Pass a measure for its deps + dependents.
Inputs: measure.
pbi_restore_backupA
Restore a backup file (path from pbi_list_backups) over its original.
Inputs: backup (required).
pbi_set_projectB
Point the model server at a Power BI Project (.pbip). Call this first.
Inputs: path (required).
pbi_update_measureB
Update an existing measure's DAX/format/folder. Omitted fields are kept.
Inputs: name (required), table (required), dax, format, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct action (e.g., create vs. bulk create, list measures vs. get model) with no overlap. Even similar tools like pbi_create_measure and pbi_bulk_create_measures are clearly separated by batch vs. single.
All tools start with 'pbi_' followed by a verb_noun pattern for most (pbi_list_measures, pbi_create_measure), but pbi_model_lineage uses noun_verb, breaking the pattern. Still, the naming is clear and readable overall.
With 13 tools covering project setup, model inspection, measure CRUD, column and relationship creation, and backup management, the count is well-scoped for the Power BI model domain—not too few or too many.
The set covers core operations well (measure CRUD, column/relationship creation, calc groups, backups), but lacks update/delete for columns, relationships, and calc groups, leaving some lifecycle gaps.
Maintenance
Related MCP Connectors
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
30+ deterministic dev and delivery tools: linting, metrics, diagrams, model advice, AI-text checks.
Enterprise memory, search, and context for frontier AI. 38 tools for business intelligence.
Exactly 50 data transformation and live web verification tools for AI agents.
Related MCP Servers
- FlicenseCqualityDmaintenanceCreates, inspects, validates, and modifies Power BI Project (.pbip) folders, generating PBIR-style reports and TMDL semantic models from structured inputs.52-
- AlicenseBqualityAmaintenanceEnables AI agents to author and edit Power BI files locally (.pbix/PBIP), covering semantic models, reports, and Power Query M with 490 tools.10023 npm3Cryptographic Autonomy 1.0 (Combined Work Exception)
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to build Power BI projects end to end: data modeling (tables, DAX measures, relationships, calculation groups, roles, field parameters) against an open Power BI Desktop via TOM/XMLA, and reports (pages, visuals, formatting, bookmarks, themes) as PBIR files in a .pbip project. Every visual is cross-checked against the real model before being written, so generated dashboards don't break on open.MIT
- AlicenseBqualityCmaintenanceEnables MCP-compatible AI clients to build and modify Power BI reports through natural language, including pages, visuals, themes, filters, and formatting using local PBIR files without REST API keys or the Power BI service.57MIT