powerbi-analyst-mcp

Purpose

Power BI Analyst MCP is a local MCP server designed to connect Power BI semantic models to LLMs (such as Claude) for data analysis. The core bottleneck it addresses is analytical translation: the human skill and time required to turn data into decisions. This server delegates the translation work to the LLM, letting users get answers backed by live DAX simply by asking questions in natural language, without needing to know DAX or wait for an analyst.

Key Capabilities

• Cross-model compound reasoning: The agent can run multiple queries in succession, each building on the previous result, synthesizing reasoning and reaching a conclusion within minutes. For example, when asked "What is causing the EMEA profit margin decline?", Claude will explore measures, drill into markets, examine time trends, and provide an explanation.
• Natural language analysis: Any stakeholder can ask questions in natural language and get real answers backed by live DAX.
• Proactive anomaly detection: Claude can be run periodically against key measures, querying data and comparing it with prior periods, flagging in plain language situations that fall outside expected ranges.
• Self-documenting semantic model: Claude can explore the schema and generate a data dictionary for onboarding, governance, and understanding what the model contains.
• Automatic handling of large datasets: Large query results are automatically saved as local CSV, and the agent receives a compact summary (row count, column names, 5-row preview) and reads them in pages on demand.
• Accumulated query history: Every successful DAX query is recorded in a local JSONL audit trail, including the user's question, the generated DAX, returned columns, and the CSV save location. The agent can search the history to reuse DAX patterns and result files.
• Local data security: Queries, results, and tokens do not pass through a cloud relay. The server runs locally, authenticates using the OAuth device code flow, and stores tokens in the operating system's native secure storage (Keychain/DPAPI/LibSecret).

How to Use

Prerequisites

• Power BI Pro, Premium Per User (PPU), or Premium capacity license
• Azure AD app registration (free, about 5 minutes)

Step 1 — Create an Azure AD app registration

1. Go to portal.azure.com → Azure Active Directory → App registrations → New registration.
2. Name it (e.g., PowerBI MCP), select "Accounts in this organizational directory only (Single tenant)", and click Register.
3. Under "Authentication" → "Platform configurations", add "Mobile and desktop applications", and check the redirect URI:https://login.microsoftonline.com/common/oauth2/nativeclient
4. Under "Authentication" → "Advanced settings", set "Allow public client flows" to "Yes" and save.
5. Under "API permissions" → "Add a permission" → "Power BI Service", add: Dataset.Read.All, Workspace.Read.All. If the tenant requires admin consent, ask an administrator to grant it.
6. From the "Overview" page, copy the "Application (client) ID" and "Directory (tenant) ID". Note: The Power BI tenant setting "Dataset Execute Queries REST API" must be enabled in the Power BI admin portal (Integration settings) for execute_dax to work.

Step 2 — Install and connect

The server is published on PyPI. The fastest way is to use uvx, with no manual installation or virtual environment required. Add the following to claude_desktop_config.json: Config file locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json POWERBI_TENANT_ID is required for almost all users. Set it to the Directory (tenant) ID from Step 1. Add a .cursor/mcp.json file to the project (or use the global config), then replace the uvx command block. .mcpb (MCP Bundle) is a ZIP archive that Claude Desktop can install via drag and drop, with no manual config editing required. All Python dependencies are installed automatically on first run; the only prerequisite is Python 3.10+. There are two manifests in bundle/. To build an organization bundle: edit bundle/manifest.json and set the values in mcp_config.env. POWERBI_OUTPUT_DIR is optional; if omitted, the default ~/powerbi_output is used. Distribution: share dist/*.mcpb with colleagues and drag and drop it into Claude Desktop → Settings → Developer. Both bundle/manifest.json and dist/ are gitignored, commit only the credential-free template.

Typical analysis workflow

After connecting, have the LLM naturally follow this sequence: note to always use list_apps (not list_workspaces) to discover workspace IDs. In app-managed organizations, dataset access is granted through Power BI apps, and using workspace IDs from list_workspaces may cause permission errors.

Large result handling

The summary returned for large results includes: rowCount (total number of rows), columns (column names and types), preview (first 5 rows), savedTo (absolute path to the CSV). The agent can then use read_query_result to read in pages: it returns rows, totalRows, offset, limit, and hasMore. Fetch the next page by increasing offset.

execute_dax parameters control the result size. The output directory defaults to ~/powerbi_output and can be overridden via POWERBI_OUTPUT_DIR. CSV files and query history logs are not cleaned up automatically and must be managed manually or given a retention policy.

Use cases

• Business users can get data answers without DAX knowledge
• Analysts need to quickly explore data and automatically generate explanations
• Regularly monitor key metrics and automatically flag anomalies
• Generate a data dictionary to understand the semantic model
• Handle large datasets of hundreds of thousands of rows without interrupting the AI session

Limitations

• Read-only. Creating, modifying, and deleting Power BI artifacts is not supported.
• execute_dax limits: up to 100,000 rows or 1,000,000 values per query (Power BI API hard limit).
• Rate limit: 120 DAX query requests per user per minute.
• list_tables, list_measures, and list_columns use DAX INFO.VIEW.* functions and require Import or DirectQuery models with XMLA read access enabled.
• CSV files written by execute_dax are not cleaned up automatically.
• Tokens are persisted via msal-extensions: macOS uses Keychain, Windows uses a DPAPI-encrypted file, Linux uses LibSecret (gnome-keyring/KWallet), falling back to an encrypted file if unavailable. The cache file is located at ~/.powerbi_mcp_token_cache.bin and is covered by .gitignore. The server does not log access tokens. All data access is governed by the user's own Power BI permissions (delegated OAuth 2.0, no service principal, no client secret).