BI Pixie MCP Server

Ask your AI assistant how your Power BI reports are really used, and let it work in BI Pixie for you.

The BI Pixie MCP Server connects AI assistants such as Claude, GitHub Copilot in VS Code, Cursor, Codex, Microsoft Fabric data agents and Microsoft Foundry to your BI Pixie data through the Model Context Protocol. It carries 33 tools in three families:

• 11 usage tools answer questions about adoption, engagement, satisfaction, data auditing and AI Readiness from your BI Pixie semantic model. They are read-only, and their numbers match your BI Pixie Dashboard exactly.
• 4 navigation tools let you switch to another workspace or semantic model while you chat (local install only).
• 18 management tools work in BI Pixie as you, through the BI Pixie API: read your account and plan, assess semantic models and data agents, preview and apply optimizations, add Pixies, run benchmarks and A/B tests. Anything that spends or changes something shows you a preview and asks you first. They come with the local install, and with a hosted deployment whose deployer turned them on (see Hosted deployment).

Full setup guide: bipixie.com/docs/cloud/mcp-server.

Note: Requires an active BI Pixie license and an installed BI Pixie Dashboard. "BI Pixie" is a trademark of DataChant. This package is a client and grants no rights to the BI Pixie service or data.

What you need

• A BI Pixie license and the BI Pixie Dashboard installed in a Power BI or Fabric workspace. The server reads the semantic model behind that dashboard.
• Python 3.12 or later, and uv for the uvx command.
• The Azure CLI, for the simplest sign-in (az login).
• One Power BI tenant setting: "Dataset Execute Queries REST API" turned on (Power BI Admin portal > Tenant settings > Integration settings). If it is off, every query fails with a permission error (403). This is the most common setup blocker, and it needs a Power BI administrator.
• Ordinary access to the workspace that holds the BI Pixie Dashboard, the same access you use to open the dashboard.

The local install signs in as you. It needs no app registration, no service principal and no administrator consent.

Set up

1. Run the guided setup

uvx bipixie-mcp

Run in a terminal with no settings yet, this starts a short guided setup. It signs you in (reusing az login when it can), lists the workspaces you can open, flags your BI Pixie semantic models, lets you pick one from a numbered menu, runs a one-row test query, offers the BI Pixie API application ID for the management tools and confirms it by reading your BI Pixie account once, and writes a .env file with a ready-to-paste registration block. Run uvx bipixie-mcp setup to go through it again at any time.

When your AI assistant starts the server it never prompts; it reads the settings below instead. bipixie-mcp --version prints the version you have installed.

2. The settings

Five settings identify you, your data and the BI Pixie API:

BIPIXIE_MCP_TENANT_ID=<your-entra-tenant-guid>
BIPIXIE_MCP_WORKSPACE_NAME=<workspace that holds the BI Pixie Dashboard>
BIPIXIE_MCP_DATASET_NAME=BI Pixie Dashboard
BIPIXIE_MCP_AUTH_MODE=azure_cli
BIPIXIE_MCP_API_APP_ID=114a7e20-3796-4ddd-ab99-568a78b7759b

• Tenant: your own Microsoft Entra tenant, the one that holds your Power BI workspace. az account show --query tenantId -o tsv prints it after az login.
• Workspace: its display name, or its GUID in BIPIXIE_MCP_WORKSPACE_ID.
• Semantic model: BI Pixie names it BI Pixie Dashboard when it installs the dashboard. Leave the setting out and the server looks for BI Pixie Dashboard or BI Pixie on its own.
• Sign-in: azure_cli reuses your az login. Without the Azure CLI, bipixie-mcp setup signs you in through your browser (interactive), or with a short code for a machine without a browser (device_code). Your sign-in is kept, so you are not asked again when your assistant restarts. A server your assistant started never shows a code: when your sign-in has run out, it asks you to run bipixie-mcp setup in a terminal.
• BI Pixie API application ID: turns on the management tools. Without it the server carries the usage and navigation tools alone.

3. Register the server with your assistant

Claude Code, Claude Desktop or Cursor. Add it to your project's .mcp.json:

{
  "mcpServers": {
    "bipixie": {
      "command": "uvx",
      "args": ["bipixie-mcp"],
      "env": {
        "BIPIXIE_MCP_TENANT_ID": "<your-entra-tenant-guid>",
        "BIPIXIE_MCP_WORKSPACE_NAME": "<your-workspace-name>",
        "BIPIXIE_MCP_DATASET_NAME": "BI Pixie Dashboard",
        "BIPIXIE_MCP_AUTH_MODE": "azure_cli",
        "BIPIXIE_MCP_API_APP_ID": "114a7e20-3796-4ddd-ab99-568a78b7759b"
      }
    }
  }
}

VS Code. Register it in one click, then add the same env block to .vscode/mcp.json:

BI Pixie customers can also install it from the AI Assistants page of the BI Pixie portal, with the workspace and semantic model already filled in.

Codex. Add it to ~/.codex/config.toml:

[mcp_servers.bipixie]
command = "uvx"
args = ["bipixie-mcp"]

[mcp_servers.bipixie.env]
BIPIXIE_MCP_TENANT_ID = "<your-entra-tenant-guid>"
BIPIXIE_MCP_WORKSPACE_NAME = "<your-workspace-name>"
BIPIXIE_MCP_DATASET_NAME = "BI Pixie Dashboard"
BIPIXIE_MCP_AUTH_MODE = "azure_cli"
BIPIXIE_MCP_API_APP_ID = "114a7e20-3796-4ddd-ab99-568a78b7759b"

4. Check that it works

Restart your assistant, then ask two questions:

1. "Describe the BI Pixie semantic model." You should see its tables, its measures and the date your data runs through. This confirms the usage tools reach your semantic model.
2. "What is my BI Pixie plan?" You should see your account, your plan and what is left of your allowances today and this month (get_account). This confirms the management tools reach the BI Pixie API as you.

If the first answer works and the second does not, check BIPIXIE_MCP_API_APP_ID and that you signed in with az login.

What you can ask

• "Which of my reports are used the most? Which are unused and could be retired?"
• "How many monthly and daily active users do I have, and what is my DAU/MAU?"
• "Which pages in the Executive Dashboard get the most clicks and time spent?"
• "What are my CSAT and NPS, and which reports pull satisfaction down?"
• "Which columns of my semantic model do people filter on most?"
• "Which of my semantic models are ready for AI?"
• "Assess the Sales semantic model, then show me what BI Pixie would change."
• "Run the benchmark on my data agent and tell me which AI answered."

Ask your assistant to "suggest questions" for a menu of examples grouped by topic.

Usage tools (11)

Read-only. They query your BI Pixie semantic model and change nothing. Every answer carries a freshness footer (data_through, the last date with data, and last_refresh_utc, the semantic model's last refresh), and the tools default to the 30 days before data_through. Pass days=0 for all of your history. Several tools answer more than one question, and their view says which.

Tools that became views. Earlier versions had 23 usage tools. If a saved prompt or an agent's instructions name one of these, use its new home:

Data auditing returns your business data. The data_audit tool returns the values people selected in your reports, such as a customer name, a region or a price. BIPIXIE_MCP_PII_COLUMNS_ALLOWED covers user names and IP addresses only, never those values. A value with a distinct count of 1 is a click on that value; a larger distinct count is a view of a span of values, so whether one value inside it was seen is approximate.

AI Readiness results. When your BI Pixie Dashboard holds AI Readiness results, describe_model says so and ai_readiness_scores ranks them. With data residency on, those results live in your own Lakehouse and are read through your semantic model only. No table holds an AI's answer to a benchmark question, a correct value or a DAX query, so no tool can return one.

Navigation tools (4)

Local install only. Point the server at another workspace or semantic model without editing settings. A switch lasts until the server restarts, and you only ever see what your own Power BI account can open. Set BIPIXIE_MCP_ALLOW_TARGET_SWITCHING=false to keep the server on the configured semantic model.

Management tools (18)

Local install only, and only when signed in as a person (azure_cli, device_code or interactive). They act through the BI Pixie API as you, with your own permissions and your own plan, within the same limits the portal applies. Every plan, Free included, can use them. No token of yours is stored by BI Pixie.

Reads. These spend nothing. A read that covers several things takes an argument naming which one, such as view or kind.

Writes. Set BIPIXIE_MCP_WRITE_TOOLS=false for a server that only reads. A write that does several things takes action (or scope, for optimizations) naming which one.

You are asked first. Every write that spends an allowance, claims a tracked item, changes an item or deletes a result answers a preview on its first call and does nothing: what it will do, to which item, and what it would spend, in the numbers your portal shows. The question names each item as your portal does, for example Assess the AI Readiness of the semantic model "Sales" in the workspace "Finance", and ends with the ids, which tell apart two items with the same name. Where a name cannot be read, the question says the id instead. Where your AI assistant can ask you a question on the server's behalf, BI Pixie puts the question straight to you there, and one call does both. Only you see that question, so the answer tells your assistant what was asked and what you said: askedThePerson, personAnswered, and the question itself in askedQuestion. Without them an assistant has no way to know you were asked, and may report that the write went ahead unasked. A write you declined carries the question back too. Otherwise, where your assistant cannot ask you, the preview carries an agreement that it brings back on a second call once you agree. An agreement is good once, for that one action, for ten minutes, and an invented one is refused. preview_optimization and the coverage check of prepare_benchmark_questions spend nothing and change nothing, so they answer at once.

How you are asked is yours to choose. BIPIXIE_MCP_CONFIRM sets it, in your settings only. No tool takes it, so your AI assistant can never choose to ask you less.

Running without anyone present. An assistant run from a script (for example claude -p) has nobody to answer, so the question counts as unanswered, never as a refusal. The assistant gets the preview and its agreement, and acts on it only if the prompt you gave it already asked for exactly that change.

Never offered to an agent: proposing and writing an optimization in one unattended step, a raw call to any BI Pixie address, and adding a saved AI or replacing its key, which would put your AI provider key into the conversation. Those stay in the portal: an AI is added in AI setup, on the AI Assistants page.

Every kind of optimization at once. preview_optimization with scope set to every_kind previews them all and spends nothing. apply_optimization with the same scope writes only a preview you have read, one kind at a time, and each next kind starts only while your assistant follows the operation with wait_for_operation. revert_optimization with that scope puts back every kind the apply wrote.

Your own wording. apply_optimization takes values, your own text for an AI instruction, a description or a display folder in place of what BI Pixie proposed. The question put to you quotes each text in full, and the agreement covers that exact text.

Operations. A write answers at once with the operation it started. wait_for_operation follows it for up to BIPIXIE_MCP_WAIT_SECONDS and answers its state and, once it succeeded, its result.

Sign-in. One sign-in covers both families. With azure_cli, az login is enough: the Azure CLI is a pre-authorized client of the BI Pixie API, so nothing is registered and nothing is consented to. With device_code or interactive through BI Pixie's sign-in app, you consent once, for yourself, to Power BI's two read permissions (reading datasets and reading workspaces). The BI Pixie API then follows without a second consent, because BI Pixie's sign-in app is pre-authorized for it. A permission a call needs and you have not granted is answered with the API's own consent link. Tenant administrator consent is never needed and never asked for.

Privacy and security

• Usage tools are read-only. They run read queries only. Write, delete and refresh commands are refused before they reach Power BI.
• Management tools ask first, as described above, and act as you within your own plan.
• It runs as you. The local install uses your own Microsoft sign-in, so it reaches only what your Power BI account and your BI Pixie account can already reach.
• Personal data follows your dashboard. When your BI Pixie semantic model holds user names or IP addresses, the server returns them as your BI Pixie Dashboard shows them. Set BIPIXIE_MCP_PII_COLUMNS_ALLOWED=false to strip them from every result. A hosted deployment strips them by default.
• Your saved sign-in. With device_code or interactive, the sign-in is saved under the name bipixie-mcp in .IdentityService in your user profile, so a restart is silent. It holds a refresh token, so treat it like a password. On Windows it is %LOCALAPPDATA%\.IdentityService\bipixie-mcp.nocae, encrypted for your Windows account. On macOS the secret is in your login Keychain. On Linux it is ~/.IdentityService/bipixie-mcp.nocae, encrypted when a desktop keyring is available and saved as plain text when it is not (over SSH or in a container, for example), in which case chmod 600 protects it. Delete it to sign out. With azure_cli, the Azure CLI keeps your sign-in and the server saves nothing.
• Secrets stay out of logs. All logs go to stderr, and a redacting filter masks GUIDs and long hex strings. A .env that holds a client secret belongs outside source control.

Configuration reference

Settings are read from environment variables or from a .env file in the working directory.

Self-hosted BI Pixie uses the same settings with your own values: your tenant, your workspace, your own BI Pixie API's application ID and address, and BIPIXIE_MCP_DATASET_NAME left unset or set to your semantic model's name.

Hosted deployment

The same server can run as an always-on endpoint in your Azure environment, so Microsoft Fabric data agents, Microsoft Foundry and your team can reach it with no local install. A hosted deployment runs under a managed identity or a service principal, carries the 11 usage tools, and needs the Power BI tenant setting "Allow service principals to use Power BI APIs". When its deployer turns them on, it also carries the management reads, which act for the person who signed in to it, never as the deployment itself: each person allows that once, for themselves, the first time they use one. Its deployer can also turn on the management writes. Every write is then agreed by that person in the conversation, and nobody is ever asked less. It is an enterprise setup: see Deploy the BI Pixie MCP Server and contact support to plan it. The container image is ghcr.io/bi-pixie/bipixie-mcp.

Troubleshooting

• Every query fails with a permission error (403): the "Dataset Execute Queries REST API" tenant setting is off, or your account cannot open the workspace. Ask your Power BI administrator to turn the setting on and confirm your workspace access.
• "No semantic model named ..." or "No dataset named ...": check the workspace name, and set BIPIXIE_MCP_DATASET_NAME to your semantic model's name exactly as it appears in the workspace. BI Pixie names it BI Pixie Dashboard when it installs the dashboard.
• Wrong data or no results: confirm BIPIXIE_MCP_TENANT_ID is the tenant that holds your Power BI workspace.
• The usage tools answer but "What is my BI Pixie plan?" does not: set BIPIXIE_MCP_API_APP_ID, sign in as a person (az login with azure_cli), and use the local install. A hosted deployment has the management reads only when its deployer turned them on, and only for a caller signed in as a person.

Support and license

Setup guide: bipixie.com/docs/cloud/mcp-server. Support: bipixie.com/docs/cloud/contact-support or support@bipixie.com.

MIT. The full text is in the bundled LICENSE file.

NOTICE: Requires an active BI Pixie license and an installed BI Pixie Dashboard. "BI Pixie" is a trademark of DataChant. This package is a client connector and grants no rights to the BI Pixie service or its data.