Skip to main content
Glama
nguyenanhducdeveloper86

mcp-powerBI

by nguyenanhducdeveloper86
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-powerBI

Claude-compatible MCP server for discovering Fabric/Power BI workspaces and semantic models.

This repo is intentionally based around Microsoft's official powerbi-modeling-mcp:

  • get_catalog, list_workspaces, and list_semantic_models use the Power BI REST API for tenant/workspace discovery.

  • list_semantic_models_in_workspace_via_modeling_mcp launches Microsoft @microsoft/powerbi-modeling-mcp and uses its XMLA/TOM auth path to enumerate semantic models inside a known workspace.

That split is necessary because Microsoft Power BI Modeling MCP can connect and model/query semantic models, but it does not expose a tenant-wide workspace discovery tool.

Tools

  • auth_status

  • start_device_login

  • complete_device_login

  • list_workspaces

  • list_semantic_models

  • get_catalog

  • list_semantic_models_in_workspace_via_modeling_mcp

  • get_known_workspace_catalog

  • execute_dax_query

Related MCP server: Power BI MCP for Claude

Install

npm install
npm run setup
npm run build

npm run setup asks for:

  • Azure app display name

  • Directory tenant ID/domain

  • Application client ID

  • Client secret value

  • Microsoft powerbi-modeling-mcp command and args

  • Known workspace names

  • Default CEO workspace

  • Optional default semantic model fallback

It writes a local .env file with mode 0600. The MCP server loads this file automatically on start.

Claude Desktop config

Use the built JS after npm run build.

For this machine, start from docs/claude-desktop-config.example.json. It points the wrapper to the already installed Microsoft native binary:

/Users/ducna/.codex/mcp/powerbi-modeling-mcp/node_modules/@microsoft/powerbi-modeling-mcp-darwin-arm64/dist/powerbi-modeling-mcp

Generic service-principal config:

{
  "mcpServers": {
    "mcp-powerbi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-powerBI/dist/server.js"],
      "env": {
        "POWERBI_TENANT": "vnu.edu.vn",
        "POWERBI_CLIENT_ID": "<app-client-id>",
        "POWERBI_CLIENT_SECRET": "<client-secret-value>",
        "POWERBI_MODELING_MCP_COMMAND": "/absolute/path/to/powerbi-modeling-mcp",
        "POWERBI_MODELING_MCP_ARGS": "--start"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "mcp-powerbi": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-powerBI/src/server.ts"]
    }
  }
}

Authentication

The server checks auth in this order:

  1. POWERBI_ACCESS_TOKEN

  2. service principal: POWERBI_TENANT, POWERBI_CLIENT_ID, POWERBI_CLIENT_SECRET

  3. cached delegated user token from start_device_login / complete_device_login

For production Claude usage, service principal is the most reliable option.

Power BI tenant/admin requirements:

  • Enable Allow service principals to use Power BI APIs.

  • Add the service principal to the relevant workspaces, or to an allowed security group.

  • App/API permissions should allow workspace and dataset reads. In practice this normally means Power BI REST API application permissions such as Workspace.Read.All and Dataset.Read.All, with admin consent where required.

  • Power BI Remote MCP Preview is a separate tenant setting for Microsoft's hosted remote MCP endpoint. It is not the same as allowing service principals to call Power BI APIs.

Usage Examples

Ask Claude:

Use mcp-powerbi to get the full catalog of workspaces and semantic models.

or:

Use mcp-powerbi to list semantic models in workspace test-mcp via Microsoft Modeling MCP.

The second path works when the workspace name is already known and Microsoft powerbi-modeling-mcp can authenticate to XMLA. If the workspace/model is not provided, Claude should call get_catalog first. If REST authentication is unavailable, Claude should ask the user for the workspace name instead of guessing.

For a CEO workflow, set:

POWERBI_KNOWN_WORKSPACES=test-mcp
POWERBI_DEFAULT_WORKSPACE=test-mcp
# Optional fallback only. Prefer letting Claude choose from workspace schema.
# POWERBI_DEFAULT_SEMANTIC_MODEL=hospital

Then Claude can use get_known_workspace_catalog to list models from configured workspaces without REST auth, choose the relevant semantic model from schema/context, and call execute_dax_query for follow-up business questions. The wrapper keeps the Microsoft Modeling MCP process alive, so repeated questions reuse the same process and should reduce repeated login prompts.

CEO Operating Mode

For the simplest CEO experience:

  • Keep Claude Desktop and this MCP server running during the working session.

  • Avoid restarting Claude between related questions.

  • Configure POWERBI_DEFAULT_WORKSPACE and POWERBI_DEFAULT_SEMANTIC_MODEL.

  • Configure POWERBI_KNOWN_WORKSPACES and POWERBI_DEFAULT_WORKSPACE.

  • Treat POWERBI_DEFAULT_SEMANTIC_MODEL as an optional fallback, not a required CEO input.

  • Ask business questions in plain language; Claude should generate DAX and call execute_dax_query.

The first query in a fresh session can still trigger Microsoft authentication. Follow-up queries in the same running MCP session reuse the existing Microsoft Modeling MCP process and connection.

Environment

Copy .env.example for local shell usage:

cp .env.example .env

Then export values before running:

set -a
source .env
set +a
npm run dev

Notes

  • list_workspaces uses GET https://api.powerbi.com/v1.0/myorg/groups.

  • list_semantic_models uses GET /datasets for My workspace or GET /groups/{groupId}/datasets for a workspace.

  • The Microsoft Modeling MCP bridge uses npx -y @microsoft/powerbi-modeling-mcp@latest --start by default. Override with POWERBI_MODELING_MCP_COMMAND and POWERBI_MODELING_MCP_ARGS if you have a signed local binary.

  • Local verification notes are in docs/verification.md.

Available Tools

7 tools
auth_statusPower BI auth statusA

Show which Power BI authentication mode is configured without exposing tokens.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

The description discloses that tokens are not exposed, a key safety trait. However, with no annotations, it lacks details on prerequisites (e.g., requires prior authentication) or 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.

Conciseness5/5

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

Single sentence, front-loaded with the action and key constraint, no superfluous text.

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?

Complete enough for a simple parameterless tool. Minor gap: does not specify the output format (e.g., string, structured data), but the purpose is clear.

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?

With zero parameters and full schema coverage, the description adds context about the tool's purpose. Baseline is 4 for no-parameter tools.

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 the tool shows the authentication mode without exposing tokens. The title and description align, and the tool is distinct from siblings like login flows and queries.

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

Usage Guidelines3/5

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

Usage context is implied (checking auth status before other operations), but no explicit guidance on when to use or alternatives is provided.

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

complete_device_loginComplete Power BI device loginA

Poll Microsoft for the pending device-code login and cache the token when authorization is complete.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It mentions polling and caching but lacks details on retries, timeouts, or side effects (e.g., overwriting existing tokens).

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 one sentence of 15 words, efficiently stating the tool's action without wasted words.

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

Completeness3/5

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

The description is adequate for a simple poll-and-cache tool with no parameters or output schema, but it could add context that it should be called after start_device_login and that it blocks until complete.

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?

There are zero parameters and schema coverage is 100%. The description adds no parameter info, but the baseline is 4 since no compensation is needed.

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 polls for pending device-code login and caches the token, clearly distinguishing it from siblings like start_device_login (which initiates) and auth_status (which checks status).

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

Usage Guidelines3/5

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

The description implies use after start_device_login but provides no explicit guidance on when to use this tool versus alternatives or prerequisites.

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

get_catalogGet workspace and semantic model catalogA

Return all visible workspaces and semantic models via Power BI REST API. This is the preferred tool for open-ended questions such as 'which model should I use?' or 'what workspaces can I access?'.

ParametersJSON Schema
NameRequiredDescriptionDefault
includeMyWorkspaceNoInclude My workspace datasets.

TDQS

A3.8/5.0
Behavior2/5

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

No annotations are provided, and the description only mentions it uses the Power BI REST API without disclosing behavioral traits like safety, side effects, or rate limits. It doesn't confirm it is read-only or describe any potential blocking or pagination.

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 consists of two concise sentences: one stating the action and resource, the other providing usage context. No extraneous information.

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 the tool has only one parameter and no output schema, the description covers its purpose and usage context well. However, it doesn't describe the output structure, which could be helpful for an AI agent.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents the single boolean parameter fully. The description adds no additional meaning about the parameter beyond what is in the 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?

The description clearly states it returns 'all visible workspaces and semantic models' and provides specific usage examples like 'which model should I use?' Distinguishes from siblings like list_workspaces which returns only 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?

The description identifies this as the 'preferred tool for open-ended questions' and gives example queries. While it doesn't explicitly exclude specific scenarios, the context is clear about its intended use.

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

list_semantic_modelsList semantic modelsA

List semantic models in My workspace or in a specific workspace by id. Use list_workspaces first to resolve workspace ids. If workspace discovery is not authenticated and the user did not name a workspace, ask the user which workspace to use.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceIdNoWorkspace/group id. Omit for My workspace.

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are present, so the description must disclose behavior fully. It only mentions listing models and workspace selection, but omits details about permissions, rate limits, or potential errors.

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 short and front-loaded with the main purpose. It uses two sentences effectively without redundancy, but could be slightly more structured.

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?

For a simple list tool with one optional parameter and no output schema, the description covers the core functionality, usage prerequisites, and a fallback instruction. It is adequately complete.

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

Parameters3/5

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

Schema coverage is 100% with the workspaceId parameter described adequately in the schema. The description adds contextual advice but does not significantly enhance parameter understanding beyond what the schema provides.

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 clearly states it lists semantic models in My workspace or a specific workspace by id. It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like list_semantic_models_in_workspace_via_modeling_mcp.

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 guidance to use list_workspaces first to resolve workspace ids and instructions for handling authentication and user input. Lacks explicit exclusion of when not to use this tool.

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

list_semantic_models_in_workspace_via_modeling_mcpList semantic models in known workspace via Microsoft Modeling MCPA

Use Microsoft powerbi-modeling-mcp/XMLA auth to list semantic models inside a known workspace name. This is a fallback when REST workspace discovery auth is unavailable. The workspace name must be explicit; if it is missing, ask the user instead of guessing.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceNameYesExact Fabric/Power BI workspace name, for example 'test-mcp'.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description adds value by disclosing the authentication method (XMLA) and the fallback nature. It does not describe side effects or failure modes, but for a read-only list operation, the behavioral context is sufficient.

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?

Three sentences with no waste: first sentence states action and auth, second gives fallback context, third gives parameter instruction. Front-loaded with key information.

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?

For a simple listing tool with one parameter, the description covers purpose, usage context, and parameter guidance. It does not explain the return format, but given no output schema, this is acceptable. The description is complete enough for an agent to use 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?

The schema covers the single parameter with description. The description reinforces the requirement for an explicit workspace name and provides guidance on handling missing values, adding meaning beyond the 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?

The description states the action: list semantic models in a known workspace using XMLA auth, and distinguishes it as a fallback from REST-based tools. This clearly identifies the tool's purpose and separates it from siblings like 'list_semantic_models'.

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 states this tool is a fallback when REST workspace discovery auth is unavailable, providing clear when-to-use guidance. It also instructs to ask the user if workspace name is missing instead of guessing, offering a usage best practice.

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

list_workspacesList Power BI/Fabric workspacesA

List all Fabric/Power BI workspaces visible to the authenticated account through the Power BI REST API. Use this first when the user does not provide a workspace name or id.

ParametersJSON Schema
NameRequiredDescriptionDefault
includeMyWorkspaceNoInclude the personal 'My workspace' pseudo-workspace.

TDQS

A3.9/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It only mentions 'authenticated account' but lacks details like authentication requirements, rate limits, or behavior when no workspaces exist.

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 two sentences with no wasted words. It front-loads the purpose and immediately follows with usage guidance.

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

Completeness3/5

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

The tool has no output schema, but the description does not mention what is returned (e.g., list of workspace objects with properties). For a simple tool, it is adequate but could be more complete.

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

Parameters3/5

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

Schema coverage is 100% (parameter is described in schema). The main description does not add parameter details beyond the schema, so baseline of 3 is appropriate.

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 it lists all workspaces visible to the authenticated account via the Power BI REST API, which is a specific verb+resource combination. It distinguishes from siblings like list_semantic_models which list models.

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 says 'Use this first when the user does not provide a workspace name or id,' giving explicit guidance on when to use this tool versus alternatives.

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

start_device_loginStart Power BI device loginA

Start delegated user device-code login for Power BI REST API. Use only for one-time local setup; service principal is recommended for production.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior2/5

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

No annotations provided, so description must carry full burden. It does not disclose what the tool returns (e.g., a user code), how it behaves (blocking vs. async), or prerequisites, leaving significant gaps.

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?

Two sentences, front-loaded with purpose, followed by usage guidance. No wasted words, highly efficient.

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

Completeness2/5

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

Given the flow involving complete_device_login and auth_status, the description lacks context about the login process, expected output, or next steps, making it incomplete for an autonomous agent.

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?

No parameters exist, so baseline score of 4 applies. Description does not need to add parameter info.

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 the verb (start) and resource (delegated user device-code login for Power BI REST API), and distinguishes from siblings like complete_device_login by specifying it's for starting the login process.

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?

Explicitly states when to use (one-time local setup) and recommends an alternative (service principal for production), providing clear guidance.

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.0
    • First observedauth_status
    • First observedcomplete_device_login
    • First observedget_catalog
    • First observedlist_semantic_models
    • First observedlist_semantic_models_in_workspace_via_modeling_mcp
    • First observedlist_workspaces
    • First observedstart_device_login
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Most tools have distinct purposes, but 'get_catalog' overlaps with 'list_workspaces' and 'list_semantic_models' by combining their functionality. The descriptions help differentiate, but some confusion is possible.

Naming Consistency4/5

All names use snake_case and mostly follow a verb_noun pattern. Minor deviations include 'auth_status' (abbreviation) and the very long 'list_semantic_models_in_workspace_via_modeling_mcp', but overall consistent.

Tool Count5/5

7 tools is a reasonable number for a Power BI discovery-focused server. Each tool serves a clear role without excessive redundancy.

Completeness3/5

The tool set covers authentication and read-only discovery well, but lacks any create, update, delete, or execute operations. For a full Power BI management surface, this is notably incomplete.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • 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