Skip to main content
Glama
jdestef90

Power BI MCP Server

by jdestef90
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Power BI MCP Server (PBI_MCP)

A standalone Model Context Protocol (MCP) server for Power BI authoring and editing that works exclusively with local .pbip files (no Microsoft Cloud or Azure authentication required).

1. Core Architecture

The server implements a Dual-Engine Architecture to cleanly manage the two distinct data layers within a Power BI project (.pbip):

                     ┌──────────────────────────┐
                     │   Model Context Protocol │
                     │   (Stdio MCP Server)     │
                     └─────────────┬────────────┘
                                   │
         ┌─────────────────────────┴─────────────────────────┐
         ▼                                                   ▼
┌──────────────────────────────┐            ┌──────────────────────────────┐
│ Engine A: Semantic Model     │            │ Engine B: Report Layout      │
│ (The "Brain")                │            │ (The "Body")                 │
│ - TMDL Parser & AST          │            │ - JSON Shadow Model          │
│ - Round-Trip Fidelity        │            │ - Path-based visual queries  │
│ - Zero-diff formatting       │            │ - Embedded JSON decoding     │
└──────────────┬───────────────┘            └──────────────┬───────────────┘
               │                                           │
               └───────────────────┬───────────────────────┘
                                   │
                                   ▼
                   ┌───────────────────────────────┐
                   │ Cross-Layer Integrity Engine  │
                   │ - Reference-Aware Renames     │
                   │ - Bound Identifier Rewriting  │
                   │ - Post-Write Safety Validator │
                   └───────────────────────────────┘

  • Engine A: Semantic Model (TMDL): Parses and serializes tabular model definitions (.tmdl). Provides typed Pydantic models for tables, columns, and measures, with 100% round-trip fidelity preserving indentation, comments, and whitespace to prevent noisy git diffs.

  • Engine B: Report Layout (JSON Shadow Model): Ingests deeply nested report.json files, decodes embedded JSON strings (config, query, dataTransforms), and exposes a flat path-based addressing scheme and JMESPath querying.

  • Cross-Layer Integrity & Safety Net: Coordinates atomic renames between TMDL and report layout JSON. Prevents destructive naive substring replacement, and runs an automated syntax safety net after writes.

  • In-Memory State Cache: Uses os.path.getmtime timestamps to avoid redundant parsing across agent turns.

Related MCP server: Power BI Desktop Local MCP Server

2. MCP Tools Overview

The server registers 11 tools over standard input/output (stdio):

Semantic Model (Engine A)

Tool

Description

get_model_summary(project_path?)

Returns a high-level summary of all tables, columns, and measures without flooding context.

list_tables(project_path?)

Lists tables with column and measure counts.

get_table_schema(table_name, project_path?)

Retrieves full schema for a table including columns, measures, and partitions.

get_measure(table_name, measure_name, project_path?)

Gets DAX formula, description, formatting, and lineage tag for a measure.

update_measure_dax(table_name, measure_name, new_dax, project_path?)

Updates a measure's DAX formula in TMDL cleanly while preserving comments and whitespace.

Report Layout (Engine B)

Tool

Description

list_pages(project_path?)

Lists all report pages with names, ordinals, and visual counts.

get_page_visuals(page_name_or_id, project_path?)

Returns flat shadow models of all visuals on a page.

get_visual_property(page_name_or_id, visual_id, property_path, project_path?)

Query visual properties via path syntax (e.g. position/width, visual_type, bound_fields).

query_report_layout(jmespath_query, project_path?)

Executes JMESPath queries across the report layout shadow model.

Cross-Layer Integrity & Validation

Tool

Description

rename_measure(table_name, old_measure_name, new_measure_name, project_path?)

Renames a measure across TMDL and updates all bound references in report.json (queryRef, Name, Measure.Property, Restatement, NativeReferenceName, and DAX formulas).

validate_pbip_structure(project_path?)

Runs post-write structural and syntax validation across descriptor, TMDLs, and report layout JSON.

3. Running with Docker / Docker Compose

Prerequisites

  • Docker Engine & Docker Compose

Run with Docker Compose

docker compose up -d

Build and Run with Docker

# Build the image
docker build -t pbi-mcp-server:latest .

# Run container mounting local PBIP workspace
docker run --rm -i \
  -v $(pwd):/app/workspace:rw \
  -e PBI_WORKSPACE_PATH=/app/workspace \
  -e LOG_LEVEL=INFO \
  pbi-mcp-server:latest

4. Local Development

Installation using uv

# Create virtual environment and install dependencies
uv sync

# Or install with pip
pip install -e .

Running the Server Locally

export PBI_WORKSPACE_PATH=$(pwd)/sample_project.pbip
python -m mcp_server.main

Running Tests

pytest -v

5. Integrating with MCP Clients

Add the server to your client configuration (e.g., Claude Desktop claude_desktop_config.json or Antigravity):

{
  "mcpServers": {
    "powerbi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/pbip_project:/app/workspace:rw",
        "-e",
        "PBI_WORKSPACE_PATH=/app/workspace",
        "pbi-mcp-server:latest"
      ]
    }
  }
}

Or running directly with Python:

{
  "mcpServers": {
    "powerbi": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "env": {
        "PBI_WORKSPACE_PATH": "/absolute/path/to/pbip_project"
      }
    }
  }
}

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers