Skip to main content
Glama
gurvinder-dhillon

PowerBI MCP Server

by gurvinder-dhillon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

PowerBI MCP Server

PyPI Python Versions License: MIT

A Model Context Protocol (MCP) server that provides tools for interacting with PowerBI REST APIs. This server enables AI assistants like Claude to query PowerBI workspaces, datasets, and execute DAX queries.

WARNING

Security Best Practices

  • Never commit credentials to version control

  • Store credentials in .env files (add to .gitignore)

  • Rotate client secrets regularly in Azure AD

  • Use least-privilege access (only grant necessary workspace permissions)

  • This server has read/write access to PowerBI datasets - use with caution

✨ Features

  • Query Your Data: Run DAX queries to extract insights and analyze your PowerBI data directly through conversation

  • Discover Workspaces & Datasets: Explore what data is available across your organization's PowerBI environment

  • Understand Data Models: Get detailed schema information to know what tables, columns, and relationships exist

  • Natural Language to Insights: Ask questions about your data and get answers without opening PowerBI

See all available tools below.

Related MCP server: Power BI MCP Server

💡 What Can You Do?

Scenario

Example Prompt

Explore available data

"What workspaces do I have access to?"

Discover reports

"What reports are available in my workspace?"

Understand data schema

"Show me the schema for dataset [dataset-name]"

Monitor data freshes

"When was this dataset last refreshed?"

Check parameters

"What parameters does this dataset accept?"

Query data with DAX

"Run a DAX query to get top 10 sales by region from [dataset]"

Analyze data quality

"What tables are in the Sales dataset?"

Extract insights

"Get the list of all measures in the Financial dataset"

📋 Prerequisites

  • Azure AD Service Principal: Required for authentication. Follow the Azure AD Configuration steps below to set this up.

🔐 Azure AD Configuration

Before installing the server, you need to set up an Azure AD application with PowerBI access.

Create Azure AD App Registration

  1. Go to Azure Portal

  2. Navigate to Azure Active Directory > App registrations

  3. Click New registration

  4. Enter a name (e.g., "PowerBI MCP Server")

  5. Click Register

Get Credentials

After registration, collect these values:

  • Tenant ID: Found in app Overview page (Directory ID)

  • Client ID: Found in app Overview page (Application ID)

  • Client Secret:

    • Go to Certificates & secrets

    • Click New client secret

    • Add description and set expiry

    • Copy the secret Value (you can only see this once!)

Enable Service Principal in PowerBI

  1. Go to PowerBI Admin Portal

  2. Navigate to Tenant settings > Developer settings

  3. Enable Service principals can use PowerBI APIs

  4. Add your app to the security group or enable for entire organization

  5. Click Apply

NOTE

Service principals can access workspaces where they've been granted explicit permissions (Admin, Member, or Contributor roles).

Grant Workspace Access

For each workspace you want to access:

  1. Go to the workspace in PowerBI

  2. Click workspace settings (⚙️) > Access

  3. Click Add people or groups

  4. Search for your app name

  5. Assign role: Admin, Member, or Contributor

  6. Click Add

📦 Installation

Method 0: From PyPI (Recommended)

Once published to PyPI, this is the simplest installation method.

Add the following to your MCP client configuration file:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": ["powerbi-mcp"],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

For Claude Code (./.mcp.json in your project directory):

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": ["powerbi-mcp"],
      "env": {}
    }
  }
}

When using Claude Code, create a .env file in your project directory (where you run Claude Code from):

POWERBI_TENANT_ID=your-tenant-id-here
POWERBI_CLIENT_ID=your-client-id-here
POWERBI_CLIENT_SECRET=your-client-secret-here
TIP

The.env file should be in your working directory, not where the server is installed.

For OpenCode (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp": {
      "type": "local",
      "command": ["uvx", "powerbi-mcp"],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

After adding the configuration, restart your MCP client.

Method 1: Direct from GitHub (Development)

This method uses uvx to run the server directly from GitHub without cloning the repository.

Add the following to your MCP client configuration file:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

For Claude Code (./.mcp.json in your project directory):

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "env": {}
    }
  }
}

When using Claude Code, create a .env file in your project directory (where you run Claude Code from):

POWERBI_TENANT_ID=your-tenant-id-here
POWERBI_CLIENT_ID=your-client-id-here
POWERBI_CLIENT_SECRET=your-client-secret-here
TIP

The.env file should be in your working directory, not where the server is installed.

The server will automatically load environment variables from the .env file in your current working directory.

For OpenCode (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

After adding the configuration, restart your MCP client.

Method 2: Local Clone (Contributors)

For contributors who want to run from a local clone:

  1. Clone the repository:

git clone https://github.com/gurvinder-dhillon/powerbi-mcp.git
cd powerbi-mcp

  1. Install dependencies:

uv sync

  1. Add to your MCP client configuration:

For Claude Desktop:

{
  "mcpServers": {
    "powerbi-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

For Claude Code (./.mcp.json in your project directory):

{
  "mcpServers": {
    "powerbi-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "env": {}
    }
  }
}

For OpenCode (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp-local": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Replace /absolute/path/to/powerbi-mcp with the actual path to your cloned repository.

When using Claude Code or OpenCode, create a .env file in your project directory with your credentials (see Method 1 Claude Code section above for the format).

🚀 Quick Start

Once installed, try these steps to get started:

  1. Verify Connection: Ask Claude "What PowerBI workspaces do I have access to?"

  2. Explore Data: "Show me the datasets in workspace [workspace-name]"

  3. View Schema: "What tables are in dataset [dataset-name]?"

  4. Run a Query: "Execute this DAX query on [dataset-name]: EVALUATE TOPN(10, Sales)"

🛠️ Available Tools

Tool

Description

Key Parameters

get_workspaces

List accessible PowerBI workspaces

top, detail

get_datasets

Get datasets from workspace or "My workspace"

workspace_id, detail

get_dataset

Get detailed dataset info including schema

dataset_id, workspace_id, detail

get_reports

List PowerBI reports in workspace

workspace_id, format, detail

get_refresh_history

Get dataset refresh history with status/timestamps

dataset_id, workspace_id, top, format

get_parameters

List dataset parameters and their current values

dataset_id, workspace_id, format, detail

query_dataset

Execute DAX queries against dataset

dataset_id, dax_query, workspace_id

Tool Details

1. get_workspaces

List PowerBI workspaces accessible to the service principal.

Parameters:

  • top (optional): Number of workspaces to return (default: 100, max: 5000)

  • detail (optional): Level of detail - "concise", "normal", or "full" (default: "normal")

2. get_datasets

Get list of datasets from a workspace or "My workspace".

Parameters:

  • workspace_id (optional): Workspace ID (omit for "My workspace")

  • detail (optional): Level of detail - "concise", "normal", or "full" (default: "normal")

3. get_dataset

Get detailed information about a specific dataset including schema and tables.

Parameters:

  • dataset_id (required): Dataset ID

  • workspace_id (optional): Workspace ID (omit for "My workspace")

  • detail (optional): Level of detail - "concise", "normal", or "full" (default: "normal")

4. get_reports

List PowerBI reports in a workspace.

Parameters:

  • workspace_id (optional): Workspace ID (omit for "My workspace")

  • format (optional): Response format - "markdown" or "json" (default: "markdown")

  • detail (optional): Level of detail - "concise" or "normal" (default: "concise")

5. get_refresh_history

Get refresh history for a dataset showing recent refresh operations.

Parameters:

  • dataset_id (required): Dataset ID

  • workspace_id (optional): Workspace ID (omit for "My workspace")

  • top (optional): Number of refresh records to return (default: 5, max: 60)

  • format (optional): Response format - "markdown" or "json" (default: "markdown")

6. get_parameters

Get parameters defined in a dataset.

Parameters:

  • dataset_id (required): Dataset ID

  • workspace_id (optional): Workspace ID (omit for "My workspace")

  • format (optional): Response format - "markdown" or "json" (default: "markdown")

  • detail (optional): Level of detail - "concise" or "normal" (default: "normal")

Note: Not supported for datasets with SQL, Oracle, Teradata, SAP HANA DirectQuery connections or datasets modified via XMLA endpoint.

7. query_dataset

Execute DAX queries against a dataset.

Parameters:

  • dataset_id (required): Dataset ID

  • dax_query (required): DAX query (must start with "EVALUATE")

  • workspace_id (optional): Workspace ID (omit for "My workspace")

DAX Query Examples

Basic Table Scan:

EVALUATE
'Sales'

Top N with Sorting:

EVALUATE
TOPN(10, 'Sales', [Amount], DESC)

Filtered Results:

EVALUATE
FILTER('Sales', [Year] = 2024)

Calculated Columns:

EVALUATE
ADDCOLUMNS(
    'Sales',
    "Profit", [Revenue] - [Cost]
)

Aggregated Summary:

EVALUATE
SUMMARIZE(
    'Sales',
    'Product'[Category],
    "Total Sales", SUM('Sales'[Amount])
)

⚠️ Troubleshooting

Authentication Errors

Error: "Authentication failed"

  • Verify your POWERBI_TENANT_ID, POWERBI_CLIENT_ID, and POWERBI_CLIENT_SECRET are correct

  • Check that the client secret hasn't expired in Azure AD

  • Ensure the service principal is enabled in PowerBI Admin Portal

Permission Errors

Error: "403 Forbidden" or "Access denied"

  • Verify the service principal has been granted access to the workspace

  • Check that the workspace role is Admin, Member, or Contributor (Viewer is not sufficient for API access)

  • Confirm "Service principals can use PowerBI APIs" is enabled in PowerBI Admin Portal

Connection Issues

Server not appearing in MCP client

  • Restart your MCP client after adding the configuration

  • Check the configuration file syntax (JSON must be valid)

  • For local clone, verify the absolute path is correct

Tools not working

  • Ensure credentials are configured

  • Check the MCP client logs for detailed error messages

  • For Claude Code, verify .env file is in the current working directory

📚 Resources

💬 Feedback and Support

🤝 Contributing

See DEVELOPER_GUIDE.md for information about developing and contributing to this project.

License

This project is licensed under the MIT License.

Available Tools

7 tools
get_datasetA

Get detailed information about a specific dataset.

Retrieves comprehensive metadata about a PowerBI dataset including configuration, refresh settings, and data source information.

Use this when you need to:

  • Get detailed metadata about a specific dataset

  • Check dataset configuration and capabilities

  • Verify dataset refresh settings

  • Understand dataset storage mode and requirements

Parameters:

  • dataset_id (required): The unique identifier of the dataset

  • workspace_id (optional): Workspace (group) ID. Omit for datasets in "My workspace"

  • format: Response format - "json" or "markdown" (default: "json")

Returns: Detailed dataset information including:

  • Dataset name and ID

  • Configuration details

  • Refresh capabilities and requirements

  • Storage mode

  • Creation date

  • Identity requirements

Example usage:

  • Get dataset from My workspace: dataset_id="dataset123"

  • Get dataset from specific workspace: dataset_id="dataset123", workspace_id="workspace456"

Error handling:

  • If dataset_id not found (404), verify the ID using get_datasets

  • For permission errors, ensure service principal has read access

  • Check workspace_id matches the workspace containing the dataset

ParametersJSON Schema
NameRequiredDescriptionDefault
dataset_idYes
workspace_idNo
formatNojson

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It notes read-like behavior (retrieves metadata) and provides error handling (404, permissions). It does not mention idempotency or side effects, but the tool is clearly a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, usage, parameters, returns, examples, errors). It front-loads the key action and uses bullet points for easy scanning, with no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 params, read operation) and presence of an output schema, the description covers all necessary aspects: purpose, parameters, expected returns, examples, and error guidance. It is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaning for all three parameters: dataset_id (unique identifier), workspace_id (optional, omit for My workspace), and format (json or markdown defaults). This compensates well for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get detailed information about a specific dataset' and distinguishes from siblings like get_datasets (which lists datasets) and get_refresh_history. It uses a specific verb-resource pair and contrasts with other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists bullet-pointed use cases (e.g., 'Check dataset configuration') and includes error handling advice referencing get_datasets as an alternative. However, it does not explicitly state when not to use this tool or directly compare with siblings like get_parameters or get_reports.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_datasetsA

Get list of datasets from a specific workspace or My workspace.

Datasets in PowerBI contain the data model, including tables, columns, relationships, and measures. This tool retrieves all datasets accessible in the specified workspace.

Use this when you need to:

  • List all datasets in a workspace

  • Find a dataset ID for querying

  • Discover available data sources

  • Check dataset refresh status and configuration

Parameters:

  • workspace_id (optional): Workspace (group) ID. If not provided, returns datasets from "My workspace"

  • format: Response format - "json" or "markdown" (default: "markdown")

  • detail: Detail level - "concise" or "detailed" (default: "concise")

Returns: List of datasets with their IDs, names, and optionally detailed metadata including refresh status, storage mode, and configuration details.

Example usage:

  • Get datasets from specific workspace: workspace_id="abc123..."

  • Get datasets from My workspace: (omit workspace_id)

  • Get detailed info: detail="detailed"

Error handling:

  • If workspace_id not found, verify the ID is correct using get_workspaces

  • For permission errors, ensure service principal has read access to the workspace

  • Empty list means no datasets in the workspace or no access

ParametersJSON Schema
NameRequiredDescriptionDefault
workspace_idNo
formatNomarkdown
detailNoconcise

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains the retrieval behavior and parameters but does not explicitly state that the tool is read-only or non-destructive, which is important for an agent to understand side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening, bullet points, and sections for parameters, returns, examples, and errors. It is slightly verbose with background on Power BI datasets but overall efficiently organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three optional parameters and an output schema (not shown but present), the description covers usage, return structure (list with IDs, names, optional metadata), and error handling. It provides sufficient context for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining each parameter's purpose, defaults, and valid values (e.g., format: 'json' or 'markdown'). It clarifies the use of workspace_id for My workspace omission, adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Get list of datasets from a specific workspace or My workspace,' clearly identifying the resource and scope. It includes usage bullet points that hint at differentiation from siblings like get_dataset (single) and query_dataset (querying), but does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases (e.g., 'Find a dataset ID for querying') and error handling tips. However, it does not state when not to use this tool or directly compare with sibling tools, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_parametersA

Get parameters defined in a PowerBI dataset.

Returns parameter definitions including:

  • Name and data type

  • Current value

  • Whether parameter is required

  • Suggested values (if defined)

Useful for discovering available parameters before querying parameterized datasets.

Note: Not supported for datasets with SQL, Oracle, Teradata, SAP HANA DirectQuery connections or datasets modified via XMLA endpoint.

Parameters:

  • dataset_id (required): The dataset ID

  • workspace_id (optional): Workspace ID. Omit for datasets in "My workspace"

  • format: Response format - "markdown" or "json" (default: "markdown")

  • detail: Detail level - "concise" or "detailed" (default: "concise")

Returns: Formatted parameter information with names, types, values, and suggested values.

Example usage:

  • Get all parameters: dataset_id="abc123"

  • Get detailed info: dataset_id="abc123", detail="detailed"

  • Check specific workspace: dataset_id="abc123", workspace_id="workspace456"

Error handling:

  • If dataset_id not found, verify the ID using get_datasets

  • "Not supported" errors indicate dataset type limitations

  • Empty result means no parameters are defined

ParametersJSON Schema
NameRequiredDescriptionDefault
dataset_idYes
workspace_idNo
formatNomarkdown
detailNoconcise

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses return content, unsupported connections, and error scenarios (not found, unsupported, empty result). It does not mention idempotency or side effects, but for a read operation, transparency is good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (returns, notes, parameters, examples, error handling). It is somewhat lengthy but front-loaded with the main purpose. Every sentence adds value, though it could be slightly more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters (1 required) and output schema existence, the description is thorough: covers purpose, parameters, return fields, usage notes, unsupported scenarios, and error handling. No major gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description fully compensates. It explains each parameter: dataset_id (required), workspace_id (optional, My workspace), format (default markdown), detail (default concise). Examples clarify usage, adding meaning beyond schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'Get parameters defined in a PowerBI dataset.' It is specific with a clear verb and resource, and it distinguishes itself from sibling tools (none of which retrieve parameters).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use the tool ('Useful for discovering available parameters before querying parameterized datasets') and notes unsupported dataset types. It also provides error handling guidance. However, it does not explicitly contrast with sibling tools, but no direct alternative exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_refresh_historyA

Get refresh history for a PowerBI dataset.

Shows recent refresh operations including:

  • Status (Completed, Failed, Unknown)

  • Start and end times

  • Request ID and refresh type

  • Error messages (for failed refreshes)

Useful for monitoring data freshness and troubleshooting refresh failures.

Parameters:

  • dataset_id (required): The dataset ID

  • workspace_id (optional): Workspace ID. Omit for datasets in "My workspace"

  • top: Number of refresh records to return (default: 5, max: 60)

  • format: Response format - "markdown" or "json" (default: "markdown")

Returns: Formatted refresh history with status, timestamps, and error details for failed refreshes.

Example usage:

  • Get last 5 refreshes: dataset_id="abc123"

  • Get last 10 refreshes: dataset_id="abc123", top=10

  • Check specific workspace: dataset_id="abc123", workspace_id="workspace456"

Error handling:

  • If dataset_id not found, verify the ID using get_datasets

  • For permission errors, ensure service principal has read access

ParametersJSON Schema
NameRequiredDescriptionDefault
dataset_idYes
workspace_idNo
topNo
formatNomarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description fully covers behavior: lists returned fields, includes default values/max for top, mentions error cases, and implies read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections, but slightly verbose; front-loaded with purpose, though some redundancy exists (e.g., repeating 'Get refresh history').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return field details aren't needed; description gives sufficient overview of returns and covers usage comprehensively. Minor gap: no mention of pagination or rate limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description explains all 4 parameters in detail (required/optional, defaults, format options) and adds usage context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource ('Get refresh history for a PowerBI dataset') and distinguishes from siblings like get_dataset or query_dataset by focusing on refresh operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States use cases (monitoring data freshness, troubleshooting failures) and provides examples and error handling, but does not explicitly contrast with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_reportsA

Get PowerBI reports from a workspace.

Returns report information including:

  • Report name and ID

  • Web URL for viewing

  • Embed URL for embedding

  • Associated dataset ID

Useful for discovering available reports and getting report URLs.

Parameters:

  • workspace_id (optional): Workspace ID. Omit to get reports from "My workspace"

  • format: Response format - "json" or "markdown" (default: "markdown")

  • detail: Detail level - "concise" or "detailed" (default: "concise")

Returns: List of reports with their IDs, names, and optionally URLs and dataset IDs.

Example usage:

  • Get reports from My workspace: (omit workspace_id)

  • Get reports from specific workspace: workspace_id="abc123"

  • Get detailed info with URLs: detail="detailed"

Error handling:

  • If workspace_id not found, verify the ID using get_workspaces

  • For permission errors, ensure service principal has read access

  • Empty list means no reports in the workspace or no access

ParametersJSON Schema
NameRequiredDescriptionDefault
workspace_idNo
formatNomarkdown
detailNoconcise

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Explains return values, error cases (workspace ID not found, permission errors, empty list), and implies read-only behavior. Transparent about behavior beyond basic purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections for parameters, returns, examples, and error handling. Some redundancy (e.g., 'Returns report information including' and later list), but mostly concise and front-loaded with main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and low schema coverage, description compensates well. Explains return fields, error handling, and usage. Output schema exists but not shown; description covers return values. Could include more details on auth requirements or rate limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No input schema descriptions (0% coverage), but description fully explains each parameter: workspace_id optional (default My workspace), format options (json/markdown), detail levels (concise/detailed). Provides usage examples that clarify semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it gets PowerBI reports from a workspace, listing specific return information (report name, ID, URLs, dataset ID). Distinguishes from siblings like get_dataset (which gets a single dataset) and get_workspaces (which lists workspaces).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful context: 'Useful for discovering available reports and getting report URLs.' Includes example usage and error handling scenarios. However, does not explicitly state when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_workspacesA

Get list of PowerBI workspaces (also called groups) accessible to the service principal.

This tool retrieves all workspaces that the configured service principal has access to. Workspaces are containers for dashboards, reports, datasets, and dataflows in PowerBI.

Use this when you need to:

  • Discover available workspaces

  • Find a workspace ID for further operations

  • List all accessible PowerBI workspaces

Parameters:

  • top (optional): Maximum number of workspaces to return (1-5000, for pagination)

  • skip (optional): Number of workspaces to skip (for pagination)

  • format: Response format - "json" or "markdown" (default: "markdown")

  • detail: Detail level - "concise" or "detailed" (default: "concise")

Returns: List of workspaces with their IDs, names, and optionally detailed metadata.

Example usage:

  • Get first 10 workspaces: top=10

  • Get concise markdown list: format="markdown", detail="concise"

  • Get detailed JSON: format="json", detail="detailed"

Error handling:

  • If authentication fails, check your service principal credentials

  • If no workspaces returned, ensure service principal has workspace access

  • For permission errors, verify service principal is enabled in PowerBI admin portal

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
skipNo
formatNomarkdown
detailNoconcise

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description fully discloses behavior: it retrieves workspaces, supports pagination (top/skip), offers format and detail options, and includes error handling for authentication and permissions. No hidden traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (overview, usage, parameters, returns, examples, errors) but is slightly verbose. Every sentence adds value, so it earns a high score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no annotations, and an output schema, the description covers usage, parameters, examples, and error handling comprehensively. An agent can confidently invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates fully. It explains each parameter (top for max count, skip for pagination offset, format for response type, detail for level of detail) and provides examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a list of PowerBI workspaces accessible to the service principal. It uses specific verbs ('Get list of') and distinguishes from sibling tools that focus on datasets, reports, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists use cases (discover workspaces, find workspace ID, list all accessible) and provides error handling scenarios. It lacks explicit when-not-to-use but the context of sibling tools makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_datasetA

Execute DAX (Data Analysis Expressions) queries against a PowerBI dataset.

This tool allows you to query dataset tables using DAX, PowerBI's formula language. DAX queries can retrieve data, perform calculations, and apply filters.

Use this when you need to:

  • Retrieve data from dataset tables

  • Perform calculations and aggregations

  • Filter and analyze dataset data

  • Get specific rows or aggregated results

DAX Query Syntax:

  • Basic table query: EVALUATE TableName

  • Filtered query: EVALUATE FILTER(TableName, TableName[Column] = "Value")

  • Aggregation: EVALUATE SUMMARIZE(TableName, TableName[Column], "Total", SUM(TableName[Amount]))

  • Top N: EVALUATE TOPN(10, TableName, TableName[Column], DESC)

Parameters:

  • dataset_id (required): The unique identifier of the dataset to query

  • dax_query (required): DAX query to execute (must start with EVALUATE)

  • workspace_id (optional): Workspace (group) ID. Omit for "My workspace"

  • format: Response format - "json" or "markdown" (default: "markdown")

Returns: Query results as a table with rows and columns. Markdown format presents results as formatted tables. Results are limited to 100 rows in markdown view.

Example queries:

  1. Get all rows: "EVALUATE 'Sales'"

  2. Filter data: "EVALUATE FILTER('Sales', 'Sales'[Year] = 2024)"

  3. Aggregate: "EVALUATE SUMMARIZE('Sales', 'Sales'[Category], "Total", SUM('Sales'[Amount]))"

  4. Top 10: "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)"

Error handling:

  • For syntax errors, check your DAX query starts with EVALUATE

  • If table/column not found, use get_dataset to see available schema

  • For large result sets, add filters or use TOPN to limit rows

  • Timeout errors suggest simplifying the query or adding filters

ParametersJSON Schema
NameRequiredDescriptionDefault
dataset_idYes
dax_queryYes
workspace_idNo
formatNomarkdown

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It mentions the 100-row limit in markdown, error handling, and return format. However, it does not explicitly confirm that queries are read-only, though examples suggest so.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (description, usage, syntax, parameters, returns, examples, error handling). It is front-loaded with the main purpose and every sentence adds value without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of DAX queries, the description covers all necessary aspects: purpose, parameters, return format, row limits, error handling, and references to get_dataset. It is comprehensive for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description provides clear meanings for all parameters, including workspace_id (omit for My workspace), format options, and DAX query syntax requirements. Examples further clarify usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute DAX queries against a PowerBI dataset' with a specific verb and resource. It distinguishes itself from siblings like get_dataset by focusing on querying data rather than metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists when to use the tool (retrieve data, perform calculations, filter, etc.) and provides error handling advice, including referring to get_dataset for schema. This serves as an implicit alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 7 tool updatesv0.1.2
    • First observedget_dataset
    • First observedget_datasets
    • First observedget_parameters
    • First observedget_refresh_history
    • First observedget_reports
    • First observedget_workspaces
    • First observedquery_dataset
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: singular vs list retrieval for datasets, separate tools for parameters, refresh history, reports, workspaces, and querying. No overlaps.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern, e.g., get_dataset, get_datasets, get_parameters. query_dataset uses 'query' instead of 'get' but still matches the pattern, maintaining overall consistency.

Tool Count5/5

With 7 tools covering dataset, report, workspace, parameter, refresh history, and query operations, the count is well-scoped for a focused PowerBI data retrieval server.

Completeness3/5

The server covers read operations comprehensively (list, get, query) but lacks any write capabilities (e.g., create, update, delete, refresh). This is a notable gap for full lifecycle management, though it may be sufficient for a read-only analysis tool.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Power BI MCP Server

    sulaiman013
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to interact with Power BI datasets through natural language, allowing users to query data, generate DAX, and get insights without leaving their AI assistant.
    122
    MIT

  • Power BI MCP Server

    michaelmckinleyconsulting
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to programmatically manage Power BI workspaces, reports, and dashboards while executing DAX queries and triggering dataset refreshes. It supports secure OAuth2 authentication for operations like report exporting, workspace management, and real-time push dataset updates.
    19
    4
    MIT

  • powerbi-mcp

    rajivdatta
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables discovery of Power BI workspaces and datasets, retrieval of semantic model definitions (TMDL), and execution of DAX queries through the Power BI and Microsoft Fabric REST APIs, using MSAL/WAM authentication for secure token caching.
    MIT