PBIXRay MCP Server

Info!

Those interested in this project might also be interested in this follow-up project, tabular-mcp, which allows running DAX queries against a local PowerBI model. Support is highly appreciated!

A Model Context Protocol (MCP) server for PBIXRay.

This MCP server exposes the capabilities of PBIXRay as tools and resources for LLM clients to interact with Power BI (.pbix) files.

Features

The list of tools is configurable, so you can choose which tools you want to make available to the MCP client.

Tools

Tool	Category	Description
`load_pbix_file`	Core	Load a Power BI (.pbix) file for analysis
`get_tables`	Model	List all tables in the model
`get_metadata`	Model	Get metadata about the Power BI configuration
`get_power_query`	Query	Display all M/Power Query code used for data transformation
`get_m_parameters`	Query	Display all M Parameters values
`get_model_size`	Model	Get the model size in bytes
`get_dax_tables`	Query	View DAX calculated tables
`get_dax_measures`	Query	Access DAX measures with filtering by table or measure name
`get_dax_columns`	Query	Access calculated column DAX expressions with filtering options
`get_schema`	Structure	Get details about the data model schema and column types
`get_relationships`	Structure	Get the details about the data model relationships
`get_table_contents`	Data	Retrieve the contents of a specified table with pagination
`get_statistics`	Model	Get statistics about the model with optional filtering
`get_model_summary`	Model	Get a comprehensive summary of the current Power BI model

Requirements

Python 3.13 (recommended) or Python 3.10+
uv package manager
Windows PowerShell

Check Your Python Version

python --version
# Should show Python 3.13.x (recommended) or 3.10+ minimum

Installation and Setup

First Time Setup - Create Virtual Environment

# Navigate to your project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Check Python version (must be 3.10+)
python --version

# Create virtual environment with Python 3.13
uv venv --python 3.13

# Activate the virtual environment
.venv\Scripts\Activate.ps1

# Install dependencies
uv pip install mcp pbixray numpy

# Test that everything works
python src/pbixray_server.py --help

Verification

Once everything is set up, you can test the server:

# Navigate to your project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Activate the virtual environment
.venv\Scripts\Activate.ps1

# Test the server
python src/pbixray_server.py --help

You should see output similar to:

usage: pbixray_server.py [-h] [--disallow DISALLOW [DISALLOW ...]] [--max-rows MAX_ROWS] [--page-size PAGE_SIZE]
                         [--load-file LOAD_FILE]
PBIXRay MCP Server
options:
  -h, --help            show this help message and exit
  --disallow DISALLOW [DISALLOW ...]
                        Specify tools to disable
  --max-rows MAX_ROWS   Maximum rows to return for table data (default: 10)
  --page-size PAGE_SIZE
                        Default page size for paginated results (default: 10)
  --load-file LOAD_FILE
                        Automatically load a PBIX file at startup

Claude Desktop Configuration

My Real Claude_Desktop_config.json

Path: C:\Users\guyen\AppData\Roaming\Claude

Content:

{
  "mcpServers": {
    "test-server": {
      "command": "D:\\AI\\Guyen\\Claude-mcp-agentic-system\\.venv\\Scripts\\python.exe",
      "args": ["D:\\AI\\Guyen\\Claude-mcp-agentic-system\\servers\\basic_server_clean.py"],
      "env": {}
    },
    "pbixray": {
      "command": "D:\\AI\\Guyen\\pbixray-mcp-server-main\\.venv\\Scripts\\python.exe",
      "args": ["D:\\AI\\Guyen\\pbixray-mcp-server-main\\src\\pbixray_server.py"],
      "env": {}
    },
    "powerbi": {
      "command": "D:\\Projects\\powerbi-mcp-master\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\Projects\\powerbi-mcp-master\\src\\server.py"
      ],
      "env": {
        "PYTHONPATH": "D:\\Projects\\powerbi-mcp-master",
        "OPENAI_API_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Alternative Configuration with PowerShell

If you prefer using PowerShell commands:

{
  "mcpServers": {
    "pbixray": {
      "command": "powershell.exe",
      "args": [
        "-Command",
        "cd 'd:\\AI\\Guyen\\pbixray-mcp-server-main'; .venv\\Scripts\\Activate.ps1; python src/pbixray_server.py"
      ]
    }
  }
}

Alternative Configuration with uv run

If you prefer using uv run (which handles the virtual environment automatically):

{
  "mcpServers": {
    "pbixray": {
      "command": "powershell.exe",
      "args": [
        "-Command",
        "cd 'd:\\AI\\Guyen\\pbixray-mcp-server-main'; uv run python src/pbixray_server.py"
      ]
    }
  }
}

Usage

Windows Path Usage

When using the PBIXRay MCP Server on Windows, you can use standard Windows paths directly:

# Load a PBIX file using Windows path
load_pbix_file("C:\\Users\\YourName\\Documents\\file.pbix")

# Or using forward slashes (also works)
load_pbix_file("C:/Users/YourName/Documents/file.pbix")

Command Line Options

The server supports several command line options:

--disallow [tool_names]: Disable specific tools for security reasons
--max-rows N: Set maximum number of rows returned (default: 100)
--page-size N: Set default page size for paginated results (default: 20)

Query Options

Tools support additional parameters for filtering and pagination:

Filtering by Name

Tools like get_dax_measures, get_dax_columns, get_schema and others support filtering by specific names:

# Get measures from a specific table
get_dax_measures(table_name="Sales")

# Get a specific measure
get_dax_measures(table_name="Sales", measure_name="Total Sales")

Pagination for Large Tables

The get_table_contents tool supports pagination to handle large tables efficiently:

# Get first page of Customer table (default 20 rows per page)
get_table_contents(table_name="Customer")

# Get second page with 50 rows per page
get_table_contents(table_name="Customer", page=2, page_size=50)

Development and Testing

Development Installation with uv

For developers working on the project:

Clone the repository (if not already done):

git clone https://github.com/username/pbixray-mcp.git
cd pbixray-mcp

Install Python 3.13 (if needed):
```
uv python install 3.13
```
Create virtual environment with Python 3.13:
```
uv venv --python 3.13
```
Activate virtual environment:
```
.venv\Scripts\Activate.ps1
```
Install in development mode:
```
uv pip install -e .
```
Install dependencies:
```
uv pip install mcp pbixray numpy
```

Testing with Sample Files

The repository includes sample files and test scripts to help you get started:

With activated virtual environment:

# Make sure you're in the project directory and venv is activated
cd "d:\AI\Guyen\pbixray-mcp-server-main"
.venv\Scripts\Activate.ps1

# Test with sample AdventureWorks Sales.pbix file in demo/ folder
python tests/test_with_sample.py

# Try the interactive demo
python examples/demo.py

# For isolated tests of specific features
python test_pagination.py
python test_metadata_fix.py

With uv run (handles venv automatically):

# Test with sample AdventureWorks Sales.pbix file in demo/ folder
uv run python tests/test_with_sample.py

# Try the interactive demo
uv run python examples/demo.py

# For isolated tests of specific features
uv run python test_pagination.py
uv run python test_metadata_fix.py

Development Mode

To test the server during development, use the MCP Inspector:

With activated virtual environment:

# Navigate to project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Activate virtual environment
.venv\Scripts\Activate.ps1

# Run the MCP Inspector
mcp dev src/pbixray_server.py

With uv run (handles venv automatically):

cd "d:\AI\Guyen\pbixray-mcp-server-main"
uv run mcp dev src/pbixray_server.py

This starts an interactive session where you can call tools and test responses.

Project Structure

pbixray-mcp/
├── README.md            - This file
├── INSTALLATION.md      - Detailed installation instructions
├── pyproject.toml       - uv/pip configuration
├── src/                 - Source code
│   ├── __init__.py
│   └── pbixray_server.py
├── tests/               - Test scripts
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_server.py
│   └── test_with_sample.py
├── examples/            - Example scripts and configs
│   ├── demo.py
│   └── config/
├── demo/                - Sample PBIX files
│   ├── README.md
│   └── AdventureWorks Sales.pbix
└── docs/                - Additional documentation
    └── ROADMAP.md

Alternative Installation Methods

Traditional pip Installation

You can also install PBIXRay MCP Server with pip:

pip install pbixray-mcp-server

For development with pip:

python -m venv venv
venv\Scripts\activate
pip install mcp pbixray numpy

WSL (Alternative)

If you prefer to use WSL, add the server configuration to your client configuration file:

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

WSL Path Conversion

When using the PBIXRay MCP Server in WSL with Claude Desktop on Windows, you need to be aware of path differences when loading PBIX files. Windows paths (like C:\Users\name\file.pbix) cannot be directly accessed in WSL. Instead, use WSL paths when referencing files:

Windows: C:\Users\name\Downloads\file.pbix
WSL: /mnt/c/Users/name/Downloads/file.pbix

Contributions

Contributions are much welcomed!

Credits

Hugoberry - Original PBIXRay library
rusiaaman - WCGW (This MCP was fully written by Claude using wcgw)

License

MIT License

PBIXRay MCP Server

Info!

Those interested in this project might also be interested in this follow-up project, tabular-mcp, which allows running DAX queries against a local PowerBI model. Support is highly appreciated!

A Model Context Protocol (MCP) server for PBIXRay.

This MCP server exposes the capabilities of PBIXRay as tools and resources for LLM clients to interact with Power BI (.pbix) files.

Features

The list of tools is configurable, so you can choose which tools you want to make available to the MCP client.

Tools

Tool	Category	Description
`load_pbix_file`	Core	Load a Power BI (.pbix) file for analysis
`get_tables`	Model	List all tables in the model
`get_metadata`	Model	Get metadata about the Power BI configuration
`get_power_query`	Query	Display all M/Power Query code used for data transformation
`get_m_parameters`	Query	Display all M Parameters values
`get_model_size`	Model	Get the model size in bytes
`get_dax_tables`	Query	View DAX calculated tables
`get_dax_measures`	Query	Access DAX measures with filtering by table or measure name
`get_dax_columns`	Query	Access calculated column DAX expressions with filtering options
`get_schema`	Structure	Get details about the data model schema and column types
`get_relationships`	Structure	Get the details about the data model relationships
`get_table_contents`	Data	Retrieve the contents of a specified table with pagination
`get_statistics`	Model	Get statistics about the model with optional filtering
`get_model_summary`	Model	Get a comprehensive summary of the current Power BI model

Requirements

Python 3.13 (recommended) or Python 3.10+
uv package manager
Windows PowerShell

Check Your Python Version

python --version
# Should show Python 3.13.x (recommended) or 3.10+ minimum

Installation and Setup

First Time Setup - Create Virtual Environment

# Navigate to your project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Check Python version (must be 3.10+)
python --version

# Create virtual environment with Python 3.13
uv venv --python 3.13

# Activate the virtual environment
.venv\Scripts\Activate.ps1

# Install dependencies
uv pip install mcp pbixray numpy

# Test that everything works
python src/pbixray_server.py --help

Verification

Once everything is set up, you can test the server:

# Navigate to your project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Activate the virtual environment
.venv\Scripts\Activate.ps1

# Test the server
python src/pbixray_server.py --help

You should see output similar to:

usage: pbixray_server.py [-h] [--disallow DISALLOW [DISALLOW ...]] [--max-rows MAX_ROWS] [--page-size PAGE_SIZE]
                         [--load-file LOAD_FILE]
PBIXRay MCP Server
options:
  -h, --help            show this help message and exit
  --disallow DISALLOW [DISALLOW ...]
                        Specify tools to disable
  --max-rows MAX_ROWS   Maximum rows to return for table data (default: 10)
  --page-size PAGE_SIZE
                        Default page size for paginated results (default: 10)
  --load-file LOAD_FILE
                        Automatically load a PBIX file at startup

Claude Desktop Configuration

My Real Claude_Desktop_config.json

Path: C:\Users\guyen\AppData\Roaming\Claude

Content:

{
  "mcpServers": {
    "test-server": {
      "command": "D:\\AI\\Guyen\\Claude-mcp-agentic-system\\.venv\\Scripts\\python.exe",
      "args": ["D:\\AI\\Guyen\\Claude-mcp-agentic-system\\servers\\basic_server_clean.py"],
      "env": {}
    },
    "pbixray": {
      "command": "D:\\AI\\Guyen\\pbixray-mcp-server-main\\.venv\\Scripts\\python.exe",
      "args": ["D:\\AI\\Guyen\\pbixray-mcp-server-main\\src\\pbixray_server.py"],
      "env": {}
    },
    "powerbi": {
      "command": "D:\\Projects\\powerbi-mcp-master\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\Projects\\powerbi-mcp-master\\src\\server.py"
      ],
      "env": {
        "PYTHONPATH": "D:\\Projects\\powerbi-mcp-master",
        "OPENAI_API_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Alternative Configuration with PowerShell

If you prefer using PowerShell commands:

{
  "mcpServers": {
    "pbixray": {
      "command": "powershell.exe",
      "args": [
        "-Command",
        "cd 'd:\\AI\\Guyen\\pbixray-mcp-server-main'; .venv\\Scripts\\Activate.ps1; python src/pbixray_server.py"
      ]
    }
  }
}

Alternative Configuration with uv run

If you prefer using uv run (which handles the virtual environment automatically):

{
  "mcpServers": {
    "pbixray": {
      "command": "powershell.exe",
      "args": [
        "-Command",
        "cd 'd:\\AI\\Guyen\\pbixray-mcp-server-main'; uv run python src/pbixray_server.py"
      ]
    }
  }
}

Usage

Windows Path Usage

When using the PBIXRay MCP Server on Windows, you can use standard Windows paths directly:

# Load a PBIX file using Windows path
load_pbix_file("C:\\Users\\YourName\\Documents\\file.pbix")

# Or using forward slashes (also works)
load_pbix_file("C:/Users/YourName/Documents/file.pbix")

Command Line Options

The server supports several command line options:

--disallow [tool_names]: Disable specific tools for security reasons
--max-rows N: Set maximum number of rows returned (default: 100)
--page-size N: Set default page size for paginated results (default: 20)

Query Options

Tools support additional parameters for filtering and pagination:

Filtering by Name

Tools like get_dax_measures, get_dax_columns, get_schema and others support filtering by specific names:

# Get measures from a specific table
get_dax_measures(table_name="Sales")

# Get a specific measure
get_dax_measures(table_name="Sales", measure_name="Total Sales")

Pagination for Large Tables

The get_table_contents tool supports pagination to handle large tables efficiently:

# Get first page of Customer table (default 20 rows per page)
get_table_contents(table_name="Customer")

# Get second page with 50 rows per page
get_table_contents(table_name="Customer", page=2, page_size=50)

Development and Testing

Development Installation with uv

For developers working on the project:

Clone the repository (if not already done):

git clone https://github.com/username/pbixray-mcp.git
cd pbixray-mcp

Install Python 3.13 (if needed):
```
uv python install 3.13
```
Create virtual environment with Python 3.13:
```
uv venv --python 3.13
```
Activate virtual environment:
```
.venv\Scripts\Activate.ps1
```
Install in development mode:
```
uv pip install -e .
```
Install dependencies:
```
uv pip install mcp pbixray numpy
```

Testing with Sample Files

The repository includes sample files and test scripts to help you get started:

With activated virtual environment:

# Make sure you're in the project directory and venv is activated
cd "d:\AI\Guyen\pbixray-mcp-server-main"
.venv\Scripts\Activate.ps1

# Test with sample AdventureWorks Sales.pbix file in demo/ folder
python tests/test_with_sample.py

# Try the interactive demo
python examples/demo.py

# For isolated tests of specific features
python test_pagination.py
python test_metadata_fix.py

With uv run (handles venv automatically):

# Test with sample AdventureWorks Sales.pbix file in demo/ folder
uv run python tests/test_with_sample.py

# Try the interactive demo
uv run python examples/demo.py

# For isolated tests of specific features
uv run python test_pagination.py
uv run python test_metadata_fix.py

Development Mode

To test the server during development, use the MCP Inspector:

With activated virtual environment:

# Navigate to project directory
cd "d:\AI\Guyen\pbixray-mcp-server-main"

# Activate virtual environment
.venv\Scripts\Activate.ps1

# Run the MCP Inspector
mcp dev src/pbixray_server.py

With uv run (handles venv automatically):

cd "d:\AI\Guyen\pbixray-mcp-server-main"
uv run mcp dev src/pbixray_server.py

This starts an interactive session where you can call tools and test responses.

Project Structure

pbixray-mcp/
├── README.md            - This file
├── INSTALLATION.md      - Detailed installation instructions
├── pyproject.toml       - uv/pip configuration
├── src/                 - Source code
│   ├── __init__.py
│   └── pbixray_server.py
├── tests/               - Test scripts
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_server.py
│   └── test_with_sample.py
├── examples/            - Example scripts and configs
│   ├── demo.py
│   └── config/
├── demo/                - Sample PBIX files
│   ├── README.md
│   └── AdventureWorks Sales.pbix
└── docs/                - Additional documentation
    └── ROADMAP.md

Alternative Installation Methods

Traditional pip Installation

You can also install PBIXRay MCP Server with pip:

pip install pbixray-mcp-server

For development with pip:

python -m venv venv
venv\Scripts\activate
pip install mcp pbixray numpy

WSL (Alternative)

If you prefer to use WSL, add the server configuration to your client configuration file:

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

WSL Path Conversion

Windows: C:\Users\name\Downloads\file.pbix
WSL: /mnt/c/Users/name/Downloads/file.pbix

Contributions

Contributions are much welcomed!

Credits

Hugoberry - Original PBIXRay library
rusiaaman - WCGW (This MCP was fully written by Claude using wcgw)

License

MIT License