PowerBI MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PowerBI MCP Server what workspaces do I have?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PowerBI MCP Server
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.
Security Best Practices
Never commit credentials to version control
Store credentials in
.envfiles (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
Go to Azure Portal
Navigate to Azure Active Directory > App registrations
Click New registration
Enter a name (e.g., "PowerBI MCP Server")
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
Go to PowerBI Admin Portal
Navigate to Tenant settings > Developer settings
Enable Service principals can use PowerBI APIs
Add your app to the security group or enable for entire organization
Click Apply
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:
Go to the workspace in PowerBI
Click workspace settings (⚙️) > Access
Click Add people or groups
Search for your app name
Assign role: Admin, Member, or Contributor
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-hereThe.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-hereThe.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:
Clone the repository:
git clone https://github.com/gurvinder-dhillon/powerbi-mcp.git
cd powerbi-mcpInstall dependencies:
uv syncAdd 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:
Verify Connection: Ask Claude "What PowerBI workspaces do I have access to?"
Explore Data: "Show me the datasets in workspace [workspace-name]"
View Schema: "What tables are in dataset [dataset-name]?"
Run a Query: "Execute this DAX query on [dataset-name]: EVALUATE TOPN(10, Sales)"
🛠️ Available Tools
Tool | Description | Key Parameters |
| List accessible PowerBI workspaces |
|
| Get datasets from workspace or "My workspace" |
|
| Get detailed dataset info including schema |
|
| List PowerBI reports in workspace |
|
| Get dataset refresh history with status/timestamps |
|
| List dataset parameters and their current values |
|
| Execute DAX queries against dataset |
|
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 IDworkspace_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 IDworkspace_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 IDworkspace_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 IDdax_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, andPOWERBI_CLIENT_SECRETare correctCheck 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
.envfile is in the current working directory
📚 Resources
💬 Feedback and Support
Issues: Report bugs or request features via GitHub Issues
Discussions: Ask questions in GitHub Discussions
Pull Requests: Contributions welcome! See DEVELOPER_GUIDE.md
🤝 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 toolsget_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
Inputs: dataset_id (required), workspace_id, format. Returns: result
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
Inputs: workspace_id, format, detail. Returns: result
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
Inputs: dataset_id (required), workspace_id, format, detail. Returns: result
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
Inputs: dataset_id (required), workspace_id, top, format. Returns: result
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
Inputs: workspace_id, format, detail. Returns: result
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
Inputs: top, skip, format, detail. Returns: result
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:
Get all rows: "EVALUATE 'Sales'"
Filter data: "EVALUATE FILTER('Sales', 'Sales'[Year] = 2024)"
Aggregate: "EVALUATE SUMMARIZE('Sales', 'Sales'[Category], "Total", SUM('Sales'[Amount]))"
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
Inputs: dataset_id (required), dax_query (required), workspace_id, format. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Governed BI MCP. Ask questions of live company data and list workspace sources via OAuth.
Connect AI assistants to Preset to explore data, charts, and dashboards in authorized workspaces.
Forge designed Power BI projects (.pbip) from your agent, bound to your own semantic model.
Enables AI assistants to retrieve event data and execute event management operations in Nunify.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.126MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.13 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseAqualityDmaintenanceEnables discovery of Fabric/Power BI workspaces and semantic models, execution of DAX queries, and generation of executive HTML reports with visualizations.11MIT