powerbi-agent-mcp

Connect your AI agent to your own Power BI / Microsoft Fabric tenant — and give it the rules and skills it needs to build dashboard pages that an executive can trust.

Three parts, one repo:

It comes from a real build on a shared retail tenant — an executive daily-trading report rebuilt and verified by AI agents — with everything company-specific stripped out. The company here is YourCo, items you create are prefixed ORG-, report measures RM , and every id is 00000000-0000-0000-0000-000000000000.

Why the guardrails exist

Each one was paid for on a shared tenant:

• Never touch an item you did not create. Other people's reports bind to the same model. Work on a clone. → deploy_report refuses any item name without your prefix.

• Never trigger a refresh on a shared model. It lands in the tenant's history under your name. → there is no refresh tool; refresh_history is read-only.

• The shared model is read-only. New DAX goes into the report (RM measures), never the model. → run_dax accepts EVALUATE / DEFINE only; model edits need a copy you own (see docs/modeling-mcp.md).

• A page is not done until you have seen it rendered with data, in every state a user can put it in. Validators cannot see a page. → capture_pages + the powerbi-dashboard-verify skill.

• Capacity is shared. One render pass per deploy, one batched DAX query, offline checks first.

Related MCP server: Microsoft Fabric MCP Server

Install in 10 minutes

You need Python 3.11+, the Azure CLI signed in to your tenant, Node 20+ (for Microsoft's PBIR validator), and — only for screenshots — Playwright. Full detail: docs/SETUP.md.

git clone https://github.com/HamadYMarafi/powerbi-agent-mcp.git
cd powerbi-agent-mcp
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
az login                                               # your own identity; no service principal

cp config.example.yaml config.yaml                     # gitignored
$EDITOR config.yaml                                    # workspace.name, semantic_model.name, deploy.item_prefix
python scripts/discover.py                             # fills the ids, exports the model definition to schema/
python -m powerbi_agent_mcp --check                # loads config, mints tokens, finds your workspace → OK

Register the server with your AI host. Claude Code:

claude mcp add powerbi-agent --env POWERBI_MCP_CONFIG="$PWD/config.yaml" \
  -- "$PWD/.venv/bin/python" "$PWD/powerbi_agent_mcp/server.py"

Any other MCP host (Claude Desktop, Cursor, …) takes the same thing as JSON:

{ "mcpServers": { "powerbi-agent": {
    "command": "/absolute/path/to/repo/.venv/bin/python",
    "args": ["/absolute/path/to/repo/powerbi_agent_mcp/server.py"],
    "env": { "POWERBI_MCP_CONFIG": "/absolute/path/to/repo/config.yaml" } } } }

Then the rules and the skills:

cp rules/CLAUDE.md /path/to/your/project/CLAUDE.md     # or append to an existing one
bash skills/install.sh                                 # copies the three skills into ~/.claude/skills

In Claude Code, add Microsoft's skills for PBIR and semantic-model specifics: /plugin marketplace add microsoft/skills-for-fabric then /plugin install powerbi-authoring@fabric-collection.

One-command alternative for Claude Code (this repo is also a plugin marketplace — it registers the server and installs the three skills; you still need the pip install, az login and config.yaml above): /plugin marketplace add HamadYMarafi/powerbi-agent-mcp then /plugin install powerbi-agent@powerbi-agent-mcp.

First conversation: "Call connection_status, then list_workspaces, then run_dax with EVALUATE ROW("ok", 1)." Three tools, no change to the tenant.

The tools

What it will never do

• Update or delete an item whose name does not start with your prefix (deploy.item_prefix).

• Bind a report to a model that is not semantic_model.id or listed in deploy.allowed_model_ids.

• Run DAX that is not EVALUATE / DEFINE.

• Trigger, retry or schedule a refresh — no such tool exists.

• Store a token. Tokens are minted in memory by the Azure CLI per request; config.yaml holds names and ids only and is gitignored; tools/secret_scan.py fails CI on a token, an e-mail address or a non-placeholder GUID.

The rules the agent follows

rules/CLAUDE.md in one breath: never touch what you did not create · prefix everything · never refresh a shared model · model read-only, DAX in the report · theme locked once stakeholders have seen it · validate after every batch and the CLI is the source of truth — never guess PBIR JSON · every number carries its basis on the canvas · a page is not done until seen rendered in every state · one page per agent, the main thread owns the shared files · deterministic checks before judgement · label every claim TESTED or UNTESTED · never commit ids, tokens or screenshots. rules/settings.example.json is a matching Claude Code permission allow-list.

The skills

For PBIR mechanics (visual JSON, formatting objects, filters, the validator, PBIP workflows) and semantic-model authoring, the skills defer to Microsoft's powerbi-authoring bundle: powerbi-report-planning, powerbi-report-design, powerbi-report-authoring, powerbi-report-management, semantic-model-authoring.

The model side

This server reads models and writes reports. To edit a semantic model (measures, tables, relationships, calculation groups, roles), Microsoft ships its own MCP — the Power BI Modeling MCP — hosted or local. docs/modeling-mcp.md has the connection recipe, the argument shape that trips people up, and the headless-server sign-in trick. The rule stands: point it only at a model you own or a copy.

Repo map

powerbi_agent_mcp/server.py   the MCP server (stdio); --check for a no-AI smoke test
scripts/                          the toolkit the server wraps; every script also runs on its own
rules/CLAUDE.md                   the universal rules — drop into your project
rules/settings.example.json       Claude Code permission allow-list for the tools
skills/                           powerbi-dashboard-build / -review / -verify + install.sh
docs/SETUP.md                     connect your AI to your Power BI, step by step
docs/modeling-mcp.md              Microsoft's Power BI Modeling MCP: recipe and rules
docs/MODEL_CONTRACT.md            what your semantic model must provide (the one thing to adapt)
docs/reference/                   the playbook the rules were distilled from: recipe, 51 traps, checklists, spec template, snippets, DAX
report-template/                  a deployable one-page PBIR report (the "Today" page) on Microsoft's stock theme
config.example.yaml               every id and rule the server reads; copy to config.yaml (gitignored)
tests/                            offline: guardrails, server surface and refusals
.claude-plugin/marketplace.json   makes this repo installable as a Claude Code plugin
.github/workflows/validate.yml    CI: tests, PBIR validation of the template, secret scan

Credits

• Microsoft skills-for-fabric (github.com/microsoft/skills-for-fabric, MIT) — the Power BI authoring skills this repo's skills defer to, and the plugin-marketplace layout this repo copies.

• @microsoft/powerbi-report-authoring-cli — the PBIR validator and catalogue: look a property up, never guess it.

• @microsoft/powerbi-modeling-mcp — the model-side MCP.

• Model Context Protocol Python SDK (mcp).

• report-template/StaticResources/SharedResources/BaseThemes/CY26SU07.json is Microsoft's own base theme copied unmodified out of a report definition; it is Microsoft's, not this repo's, and the MIT licence does not cover it. Delete it and the service supplies the same theme.

License

MIT — see LICENSE. Author: Hamad Marafi.