Skip to main content
Glama

PBI MCP Server

Local-first MCP server for inspecting, auditing, and safely editing Power BI PBIP projects (.SemanticModel TMDL and .Report PBIR layouts).


Highlights

  • Consolidated src/pbi_mcp_server/ Architecture: Clean package hierarchy separating Workspace Discovery (workspace_registry, pbip_references), Semantic Model (engine_a), Report Layout (engine_b), Cross-Layer Lineage (lineage), Standardized Mutations (mutation), Partition SQL (tmdl_sql), Analyst Superpowers (analyst), and Agent Workflows (workflows).

  • Compact 20-Tool Surface: Focused, high-leverage tools designed for LLM coding and analytics agents with optional pagination (limit, offset) and precondition guards (expected_current_expression, expected_replacements).

  • Cross-Layer Dependency Graph: Traces lineage from Partition SQL (source_tables, sql_fields) $\rightarrow$ TMDL Tables & Columns (sourceColumn) $\rightarrow$ DAX Calculated Columns & Measures $\rightarrow$ PBIR Visual Field Bindings & Report Pages.

  • Hardened Mutation Pipeline:

    • Ambiguity detection (AMBIGUOUS_WORKSPACE, AMBIGUOUS_OBJECT) before any analysis or edit.

    • Precondition verification (PRECONDITION_FAILED) to prevent overwriting stale expressions.

    • Unified diff previews (MutationDiff) during dry_run=True.

    • Multi-file atomic backups and automatic rollback (ROLLBACK_COMPLETED) if post-write TMDL or PBIR validation fails.

  • Expanded Power BI Analyst Toolkit:

    • find_unused_objects: Detects unreferenced measures, unused columns, and dead-branch (indirectly_referenced_only) objects.

    • format_dax: Formats single-line and multi-line VAR/RETURN DAX expressions to SQLBI conventions.

    • generate_measure_docs: Synthesizes lineage-aware /// TMDL documentation comments for measures.

    • check_model_bpa: Audits both Semantic Model and Report Layout against 11 Best Practice Analyzer rules (bidirectional relationships, many-to-many relationships, broken relationship endpoints, unhidden foreign keys, missing format strings, missing descriptions, direct / division, floating-point columns, complex calculated columns, broken visual bindings, empty report pages, and duplicate visuals).


Related MCP server: Power BI Desktop Local MCP Server

MCP Tools (20 Total)

1. Workspace Discovery & Lifecycle (3 tools)

Tool

Description

list_workspaces(query?, limit?, offset=0)

List discovered PBIP workspaces with deterministic workspace_ids, optionally filtered and paginated.

get_workspace(workspace?)

Get workspace paths, validity status, object counts, scan diagnostics, and BPA health_summary.

refresh_workspaces()

Re-scan configured workspace roots and refresh registry state.

2. Semantic Model Inspection & Search (5 tools)

Tool

Description

list_tables(workspace?, limit?, offset=0)

List tables with object_id, column/measure/partition counts, and Value.NativeQuery SQL status.

get_table(table_name, workspace?)

Retrieve complete table schema (columns, measures, relationships, partition metadata, and SQL source).

search_measures(query?, table?, workspace?, limit?, offset=0)

Search across measure names, qualified names, DAX formulas, and descriptions.

get_table_sql(table_name?, partition?, workspace?)

Extract partition SQL query with line numbers, M context, and parsed SQL metadata.

analyze_impact(term, workspace?)

Cross-layer upstream (SQL, partitions, columns, measures) and downstream (measures, columns, relationships, visuals, pages) impact analysis.

3. Report Layout & Visuals (3 tools)

Tool

Description

list_report_pages(workspace?, limit?, offset=0)

List report pages with object_id, display names, visual counts, and page-level filter fields.

list_visuals(page?, query?, workspace?, limit?, offset=0)

List visuals with object_id, titles, types, role-grouped field_bindings, and filter_fields.

get_visual(visual_id_or_title, page?, workspace?)

Resolve a visual unambiguously by ID or title and inspect its role-grouped field bindings.

4. Safe Mutations (4 tools)

Tool

Description

update_measure_dax(measure_name, expression, table?, create_if_missing=False, format_string?, display_folder?, description?, expected_current_expression?, expected_replacements?, workspace?, dry_run=True)

Update an existing measure's DAX or create a new measure (create_if_missing=True) with formatString, displayFolder, and unified diff output.

update_table_sql(old_text, new_text, table_name?, partition?, expected_replacements?, workspace?, dry_run=True)

Surgically replace lines or blocks inside a table's Value.NativeQuery SQL with unified diffs.

update_visual_fields(visual_id_or_title, add_fields?, remove_fields?, page?, expected_replacements?, workspace?, dry_run=True)

Add or remove measures/columns on visual roles without altering visual layout or styling.

rename_measure(old_name, new_name, table?, expected_replacements?, workspace?, dry_run=True)

Atomically rename a measure across TMDL declarations, DAX formulas, and report visuals.

5. Power BI Analyst Toolkit (4 tools)

Tool

Description

find_unused_objects(workspace?)

Identify unused measures, unused columns, and dead-branch (indirectly_referenced_only) objects.

format_dax(measure_name?, dax_expression?, table?, workspace?, dry_run=True)

Standardize DAX formatting standalone or in-place in TMDL.

generate_measure_docs(measure_name, description?, table?, workspace?, dry_run=True)

Generate and write lineage-aware /// TMDL documentation comments for a measure.

check_model_bpa(workspace?)

Audit the Semantic Model and Report Layout against 11 Best Practice Analyzer rules.

6. Validation (1 tool)

Tool

Description

validate_workspace(workspace?)

Validate TMDL syntax, balanced fences, measure expressions, and PBIR JSON integrity.


MCP Resources & Prompts (Zero Tool-Surface Overhead)

In addition to the 20 tools above, the server exposes MCP Resources (for instant context attachment) and MCP Prompts (for slash-command workflows in Claude Desktop, Cursor, or Antigravity):

MCP Resources

  • pbip://workspaces: Live JSON list of all discovered PBIP workspaces and their workspace_ids.

  • pbip://workspace/{workspace}/summary: Object counts (tables, columns, measures, relationships, partitions, calculation groups, RLS roles, pages, visuals) and BPA health_summary.

  • pbip://workspace/{workspace}/bpa: Full Best Practice Analyzer report for the workspace.

MCP Prompts

  • workflow_model_audit(workspace?): Guided 4-step Semantic Model & Report Layout audit prompt.

  • workflow_measure_update(measure_name, new_dax, workspace?): Guided 5-stage prompt for resolving, impact-analyzing, dry-running, applying, and validating a measure update or creation.


Configuration & Environment Variables

Variable

Default

Description

PBI_WORKSPACE_PATH

(None)

Default single .pbip file or workspace directory when CLI flags are omitted.

PBI_MCP_CREATE_BACKUPS

true

Create .bak backup files before applying mutations.

LOG_LEVEL

INFO

Logging verbosity (DEBUG, INFO, WARNING, ERROR). All logs route to stderr.

PBI_MCP_LOG_FORMAT

text

Set to json for structured JSON log records on stderr.

PBI_MCP_REDACT_PATHS

true

Redact sensitive user/OneDrive home directory segments in log output.


Running Locally

# Run full test suite
.venv/bin/pytest

# Start server for a single PBIP project
.venv/bin/pbi-mcp-server --workspace ./sample_project.pbip

# Start server across one or more workspace root directories
.venv/bin/pbi-mcp-server --workspace-root "/path/to/pbip-projects"

Domain & Architecture Documentation

  • GLOSSARY.md: Ubiquitous domain language for PBIP workspaces, TMDL, PBIR, lineage, and mutations.

  • docs/agent-workflows.md: Canonical multi-step agent workflow recipes and precondition guidelines.

  • docs/adr/: Architecture Decision Records (0001 through 0005).

  • docs/agents/: Engineering skill configurations for issue tracking and domain docs.

Available Tools

20 tools
analyze_impactA

Analyze where a measure or column is referenced across TMDL formulas and report visuals.

Inputs: term (required), workspace. Returns: object

check_model_bpaB

Run Best Practice Analyzer rules against the semantic model (keys, relationships, types, DAX).

Inputs: workspace. Returns: object

find_unused_objectsB

Scan the semantic model and report layout to identify unused measures and unreferenced columns.

Inputs: workspace. Returns: object

format_daxB

Standardize DAX formatting (uppercase functions, clean operator spacing) standalone or in TMDL.

Inputs: table, dry_run, workspace, measure_name, +1 more. Returns: object

generate_measure_docsC

Generate and write a /// TMDL documentation docstring for a measure.

Inputs: measure_name (required), table, dry_run, workspace, +1 more. Returns: object

get_tableA

Retrieve complete table schema including columns, measures, relationships, and SQL source.

Inputs: table_name (required), workspace. Returns: result

get_table_sqlB

Extract the partition SQL query (with line numbers and M context) for a table.

Inputs: partition, workspace, table_name. Returns: object

get_visualA

Get a visual's details and current role-grouped field bindings by ID or title.

Inputs: visual_id_or_title (required), page, workspace. Returns: result

get_workspaceB

Get metadata and object counts for a PBIP workspace.

Inputs: workspace. Returns: object

list_report_pagesA

List all report pages with their display names and visual counts.

Inputs: workspace. Returns: result

list_tablesB

List all tables in the semantic model with column/measure counts and native SQL status.

Inputs: workspace. Returns: result

list_visualsB

List visuals in the report with their titles, types, and field bindings.

Inputs: page, query, workspace. Returns: result

list_workspacesA

List discovered PBIP workspaces, optionally filtered by query.

Inputs: query. Returns: result

refresh_workspacesB

Re-scan configured workspace roots and refresh discovered PBIP projects.

Inputs: no named parameters. Returns: result

rename_measureB

Atomically rename a measure across TMDL declarations, DAX formulas, and report visuals.

Inputs: new_name (required), old_name (required), dry_run, workspace. Returns: object

search_measuresB

Find measures across the semantic model and return their table, name, DAX expression, and description.

Inputs: query, table, workspace. Returns: result

update_measure_daxA

Update a measure's DAX expression in TMDL while preserving surrounding formatting.

Inputs: expression (required), measure_name (required), table, dry_run, +1 more. Returns: object

update_table_sqlC

Surgically replace a line or block inside a table's Value.NativeQuery SQL expression.

Inputs: new_text (required), old_text (required), dry_run, partition, +3 more. Returns: object

update_visual_fieldsA

Add or remove measures and columns on a visual without modifying visual styling or layout.

Inputs: visual_id_or_title (required), page, dry_run, workspace, +2 more. Returns: object

validate_workspaceB

Run structural and syntax validation across TMDL and PBIR report JSON.

Inputs: workspace. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools target distinct resources and actions (workspace, table, measure, visual, SQL, DAX, validation). There is some overlap between analyze_impact and find_unused_objects, and between list/get pairs, but descriptions make the intended boundaries mostly clear.

    Naming Consistency5/5

    All tools use a consistent snake_case verb_noun pattern (e.g. list_workspaces, get_table, update_measure_dax, validate_workspace). Minor abbreviations like bpa are readable and do not break the convention.

    Tool Count3/5

    At 20 tools, the surface is on the heavy side for a single MCP server, though the breadth of workspace/model/report operations explains much of it. The count is borderline rather than clearly well-scoped.

    Completeness3/5

    Read and edit coverage is strong across workspaces, tables, measures, visuals, SQL, and validation. However, there are notable lifecycle gaps: no create/delete measure or table, no visual/page creation, and no relationship editing, which limits end-to-end modeling workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables local Power BI project (.pbip) automation, including model (TMDL) and report (PBIR) layer manipulation, without cloud dependencies. Provides 56 tools for building, editing, and validating reports and measures through natural language prompts.
      13
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying open Power BI Desktop models locally, including discovering instances, listing tables and measures, and running DAX queries without cloud login or publishing.
      MIT