Power BI MCP server

Power BI MCP Server enables AI assistants to interact with Power BI datasets through natural language. This server lets you query your data, generate DAX, and get insights directly within your AI assistant, transforming how you extract information from Power BI.

Installation

System Requirements

Platform	Python	.NET Runtime	ADOMD.NET	Status
Windows	3.10+	Built-in	Available	Full Support
Linux	3.10+	Available	Docker only	Docker Support
macOS	3.10+	Available	Not available	Not supported

Prerequisites

• Python 3.10 or higher
• Windows with ADOMD.NET or Docker on Linux
• SQL Server Management Studio (SSMS) or ADOMD.NET client libraries (Windows only)
• Power BI Pro/Premium with XMLA endpoint enabled
• Azure AD Service Principal with access to your Power BI dataset
• OpenAI API key (optional for natural language features)

Setup Instructions

1. Clone the repository

   git clone https://github.com/yourusername/powerbi-mcp-server.git
   cd powerbi-mcp-server
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your credentials
   

4. Test the connection

   python quickstart.py
   

Docker Setup

Build the container image:

docker build -t powerbi-mcp .

Run the server:

docker run -it --rm -e OPENAI_API_KEY=<key> powerbi-mcp

To use a custom port:

docker run -it --rm -e OPENAI_API_KEY=<key> -p 7000:7000 powerbi-mcp \
  python src/server.py --host 0.0.0.0 --port 7000

Important: Docker containers don't use .env files. Provide environment variables using docker run -e, Docker Compose, or your cloud platform.

Configuration

Required Credentials

1. Power BI XMLA Endpoint

   • Format: powerbi://api.powerbi.com/v1.0/myorg/WorkspaceName
   • Enable in Power BI Admin Portal → Workspace Settings

2. Azure AD Service Principal

   • Create in Azure Portal → App Registrations
   • Grant access in Power BI Workspace → Access settings

3. OpenAI API Key (optional)

   • Needed only for natural language features
   • Endpoints that rely on GPT models are hidden if this key is not set
   • Get from OpenAI Platform
   • Model used: gpt-4o-mini

Environment Variables

Create a .env file (OpenAI settings are optional):

# OpenAI Configuration (optional)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini  # Defaults to gpt-4o-mini

# Optional: Default Power BI Credentials
DEFAULT_TENANT_ID=your_tenant_id
DEFAULT_CLIENT_ID=your_client_id
DEFAULT_CLIENT_SECRET=your_client_secret

# Logging
LOG_LEVEL=INFO

Configure with Claude Desktop

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "powerbi": {
      "command": "python",
      "args": ["C:/path/to/powerbi-mcp-server/src/server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/powerbi-mcp-server",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Usage

Once configured, you can interact with your Power BI data through Claude:

Connect to Your Dataset

Connect to Power BI dataset at powerbi://api.powerbi.com/v1.0/myorg/YourWorkspace

Explore Your Data

What tables are available?
Show me the structure of the Sales table

Ask Questions

What are the total sales by product category?
Show me the trend of revenue over the last 12 months
Which store has the highest gross margin?

Execute Custom DAX

Execute DAX: EVALUATE SUMMARIZE(Sales, Product[Category], "Total", SUM(Sales[Amount]))

Troubleshooting

Common Issues

1. ADOMD.NET not found

   • For Windows, install SQL Server Management Studio (SSMS)
   • On Linux, use the provided Docker image which bundles the cross-platform ADOMD.NET runtime

2. Connection fails

   • Verify XMLA endpoint is enabled in Power BI
   • Check Service Principal has workspace access
   • Ensure dataset name matches exactly

3. Timeout errors

   • Increase timeout in Claude Desktop config
   • Check network connectivity to Power BI

Performance

• Connection time: 2-3 seconds
• Query execution: 1-5 seconds depending on complexity
• Token usage: ~500-2000 tokens per query with GPT-4o-mini
• Cost: ~$0.02-0.06 per day for typical usage

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "powerbi" '{"command":"python","args":["C:/path/to/powerbi-mcp-server/src/server.py"],"env":{"PYTHONPATH":"C:/path/to/powerbi-mcp-server","OPENAI_API_KEY":"your-openai-api-key"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "powerbi": {
            "command": "python",
            "args": [
                "C:/path/to/powerbi-mcp-server/src/server.py"
            ],
            "env": {
                "PYTHONPATH": "C:/path/to/powerbi-mcp-server",
                "OPENAI_API_KEY": "your-openai-api-key"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "powerbi": {
            "command": "python",
            "args": [
                "C:/path/to/powerbi-mcp-server/src/server.py"
            ],
            "env": {
                "PYTHONPATH": "C:/path/to/powerbi-mcp-server",
                "OPENAI_API_KEY": "your-openai-api-key"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect