Essential Notice!

Individuals exploring this utility may find significant relevance in its successor, the tabular-mcp project, which facilitates the execution of DAX inquiries against a locally instantiated PowerBI artifact. Community backing is highly valued!

PBIXRay MCP Gateway

This implementation functions as a Model Context Protocol (MCP) server, specifically tailored for the PBIXRay ecosystem.

This dedicated MCP endpoint exposes the comprehensive capabilities inherent in PBIXRay as actionable tools and structured resources, enabling sophisticated interaction with Power BI files (.pbix) by Large Language Model (LLM) clients.

Core Capabilities

• [x] Ingestion and comprehensive analysis of PBIX containers
• [x] Data structure schema traversal
• [x] Enumerating constituent tables within the dataset
• [x] Fetching configuration metadata from the model
• [x] Determining the aggregate file footprint (size)
• [x] Generating operational statistics for the model
• [x] Rendering a holistic summary blueprint of the data model
• [x] Query language artifact retrieval
• [x] Outputting Power Query (M) source code
• [x] Retrieving defined M variable/parameter values
• [x] Inspecting DAX constructs for computed tabular objects
• [x] Exposing the definitions of DAX calculated metrics
• [x] Examining the logic underlying DAX calculated attributes
• [x] Underlying data organization evaluation
• [x] Deriving definitive schema documentation
• [x] Mapping and documenting data entity linkages (relationships)
• [x] Accessing raw table content, subject to row limiting and paging controls

The exposed toolkit is fully subject to client-side customization; users retain the prerogative to selectively enable or suppress specific operational endpoints. This flexibility supports scenarios involving feature deprecation or the necessity to restrict access to potentially sensitive operational facets.

Available Operations (Tools)

Operation Name	Domain	Description
load_pbix_file	Foundation	Initiate the loading process for a Power BI (.pbix) artifact for subsequent analysis
get_tables	Structure	Yield a list of every defined entity (table) within the model
get_metadata	Structure	Obtain configuration and structural meta-information pertaining to the Power BI environment
get_power_query	Logic	Render the entirety of M/Power Query script utilized for data preparation procedures
get_m_parameters	Logic	Present the currently assigned values for all defined M parameters
get_model_size	Structure	Report the model's physical size, quantified in bytes
get_dax_tables	Logic	Fetch definitions for tables generated via DAX formulas
get_dax_measures	Logic	Retrieve DAX expressions for defined metrics, supporting filtering by associated table or metric identifier
get_dax_columns	Logic	Access DAX logic for calculated attributes, offering filtering mechanisms
get_schema	DataMap	Acquire detailed schematics of the data model, including column data types
get_relationships	DataMap	Obtain granular documentation concerning inter-table bindings
get_table_contents	DataFetch	Fetch the data payload from a specified entity, incorporating pagination logic
get_statistics	Structure	Provide calculated operational metrics on the model, optionally filtered
get_model_summary	Structure	Deliver a comprehensive overview report detailing the current Power BI artifact state

Deployment Guidelines

Utilizing WSL (Recommended Execution Environment)

Integrate the service configuration into your client's operational manifest. For instance, when configuring Claude Desktop:

{
  "mcpServers": {
    "pbixray": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "source ~/dev/pbixray-mcp/venv/bin/activate && python ~/dev/pbixray-mcp/src/pbixray_server.py"
      ]
    }
  }
}

Path Translation Nuances (Specifically for WSL/Claude Desktop Integration)

When operating the PBIXRay MCP Gateway within a WSL context interfacing with a Windows-based client (like Claude Desktop), precise file path translation is mandatory for artifact loading. Native Windows paths (e.g., C:\Users\name\file.pbix) are inaccessible within WSL. Users must explicitly map these paths. It is advisable to inject an instruction such as: "Crucially, recognize that the MCP server operates within WSL. Windows path conventions (e.g., C:\Users\name\file.pbix) are invalid for file references. Utilize the WSL representation instead: Windows Path: C:\Users\name\Downloads\file.pbix becomes WSL Path: /mnt/c/Users/name/Downloads/file.pbix" into project context documentation or AI prompts.

Execution Argument Modifiers

The server accommodates several operational flags at startup:

• --disallow [tool_names]: Revokes access to specified operational endpoints for security hardening.
• --max-rows N: Establishes the upper bound on row counts returned by queries (Default: 100).
• --page-size N: Sets the default row quantity for result sets employing pagination (Default: 20).

These arguments can be incorporated directly within the client configuration JSON block:

json { "mcpServers": { "pbixray": { "command": "wsl.exe", "args": [ "bash", "-c", "source ~/dev/pbixray-mcp/venv/bin/activate && python ~/dev/pbixray-mcp/src/pbixray_server.py --max-rows 100 --page-size 50 --disallow get_power_query" ], "env": {} } } }

Parameterization of Operations

Many operations permit supplementary arguments to refine retrieval, particularly for scoping or managing result volume:

Scoping via Identifier

Operations such as get_dax_measures, get_dax_columns, get_schema, among others, accept parameters to restrict the scope based on names:

# Retrieve metrics exclusively associated with the 'Sales' entity
get_dax_measures(table_name="Sales")

# Target a singular, named metric within the model
get_dax_measures(table_name="Sales", measure_name="Total Sales")

Paging Protocols for Extensive Datasets

The get_table_contents operation is engineered to manage large tables efficiently through explicit pagination controls:

# Fetch the initial segment (Page 1) of the 'Customer' entity data (utilizing the default 20 rows/page limit)
get_table_contents(table_name="Customer")

# Request the second sequential segment, specifying a custom buffer size of 50 rows
get_table_contents(table_name="Customer", page=2, page_size=50)

Development and Debugging Lifecycle

You can install the PBIXRay MCP Gateway via pip:

pip install pbixray-mcp-server

Source Code Contribution Installation

For contributors actively developing on the project source:

1. Secure a local copy of the repository: bash git clone https://github.com/username/pbixray-mcp.git cd pbixray-mcp

2. Install in an editable state: bash pip install -e .

3. If installing from a fresh clone, establish an isolated environment and pull necessary dependencies: bash python -m venv venv source venv/bin/activate # Substitute with 'venv\Scripts\activate' on Windows OS pip install mcp pbixray numpy

Validation Using Sample Artifacts

The repository is provisioned with demonstration files and utility scripts for initial validation:

# Execute tests against the sample AdventureWorks Sales.pbix artifact located in the demo/ directory
python tests/test_with_sample.py

# Initiate the interactive demonstration script
python examples/demo.py

# For focused validation of specific functionalities
python test_pagination.py
python test_metadata_fix.py

The provided test routines are structured to illustrate the proper invocation patterns for server interaction, leveraging the sample PBIX files resident in the demo/ subdirectory.

Interactive Development Testing

To facilitate real-time testing during active development, utilize the MCP Inspector utility:

# Ensure your development environment is activated first
source venv/bin/activate

# Launch the MCP Inspector session, pointing it to the server module
mcp dev src/pbixray_server.py

This action initiates an interactive shell environment permitting direct operational calls and immediate response validation.

Project Directory Layout

pbixray-mcp/
├── README.md            - Primary documentation (this file)
├── INSTALLATION.md      - Comprehensive deployment procedures
├── src/                 - Core functional source files
│   ├── __init__.py
│   └── pbixray_server.py
├── tests/               - Automated verification scripts
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_server.py
│   └── test_with_sample.py
├── examples/            - Sample execution scripts and configuration templates
│   ├── demo.py
│   └── config/
├── demo/                - Sample Power BI binaries for testing
│   ├── README.md
│   └── AdventureWorks Sales.pbix
└── docs/                - Supplementary documentation artifacts
    └── ROADMAP.md

Collaboration Policy

Contributions from the community are enthusiastically welcomed and encouraged.

Attributions

• Hugoberry - Originator of the PBIXRay library foundation
• rusiaaman - WCGW Framework (This specific MCP implementation was engineered by Claude leveraging the wcgw structure)

Governing Document (Mandated Legal Inclusion)

MIT License

---

WIKIPEDIA DIGRESSION: Business Management Utilities

Business management utilities encompass the spectrum of systems, software applications, control mechanisms, computational engines, methodologies, and frameworks utilized by organizations to navigate shifting market dynamics, secure a durable competitive foothold, and systematically elevate overall operational efficacy.

These utilities can be categorized according to the organizational function they serve—for instance, tools dedicated to strategic foresight, procedural management, data retention, personnel administration, critical decision support, performance oversight, and so forth. A functional taxonomy would generally address these primary domains:

1. Utilities for data acquisition and integrity verification across any operational unit.
2. Systems employed for monitoring and advancing core organizational processes.
3. Platforms facilitating data synthesis and informed strategic selection.

Contemporary enterprise management instrumentation has undergone radical transformation over the last decade, fueled by rapid technological acceleration. This pace makes the selection of optimal business utilities for any given corporate scenario exceedingly challenging. This complexity stems from the relentless pursuit of margin improvement, sales expansion objectives, the drive to deeply comprehend client requirements, and the imperative to deliver conforming products precisely as demanded. In this environment, executive leadership must adopt a deliberate, strategic posture toward these management instruments, rather than simply adopting the newest available option. Over-reliance on unmodified, off-the-shelf tools frequently precipitates operational fragility. Therefore, business management systems demand careful selection followed by meticulous tailoring to the organization's unique requirements, not the reverse.

Global Adoption Trends (2013 Survey Context)

A 2013 survey conducted by Bain & Company mapped the global deployment of business utilities, illustrating how their outputs align with regional imperatives, factoring in market volatility and corporate standing. The leading ten categories identified included:

Strategic planning, Client relationship management, Employee sentiment evaluation, Comparative performance analysis (Benchmarking), The Balanced Scorecard framework, Core competency definition, Outsourcing strategies, Organizational transition management programs, Supply chain orchestration, Formulation of mission/vision statements, Market segmentation studies, and Total Quality Management principles.

Business Software Applications

Software—defined as collections of computer programs used by professional staff to execute diverse operational mandates—is termed business software or an enterprise application. These solutions are deployed to enhance productivity metrics, quantify realized output, and perform various corporate tasks with precision. The domain originated with Management Information Systems (MIS), expanded into Enterprise Resource Planning (ERP), incorporated Customer Relationship Management (CRM), and has largely migrated into the sphere of cloud-based business management suites. While a measurable correlation exists between IT investment efficacy and organizational performance, value accretion hinges critically upon two factors: the thoroughness of implementation execution and the diligent process of selecting and customizing the appropriate technological assets.