Powerbi Report Mcp

Power BI Report MCP Server

Build Power BI reports with natural language — currently tested with Claude (Code, Desktop, Cowork).

Tested: Claude Code · Claude Desktop · Claude Cowork Built on the standard MCP protocol — other MCP-compatible clients should work but are not yet verified.

---

> "Create an executive summary page with 6 KPI cards, a revenue trend line chart, and a bar chart by country" > > One prompt. One batch call. Full page in Power BI Desktop.

---

What's new in 0.9

• Layout validator now reachable via pbir_validate_wireframe (v0.9.6) — same checks the test suite runs (margins, gaps, overlap, off-canvas, banner geometry), callable from agents on a single page or across the entire report
• Tier C.1 catalog reduction + pbir_guide fix (v0.9.5) — see [CHANGELOG.md](CHANGELOG.md)

What's new in 0.8

• pbir_ tool prefix — every tool name now starts with pbir_ to avoid collisions with sibling MCP servers in the same session
• Cowork plugin — drop a single .plugin file into Claude (no terminal, no Node install) — see [Quick Start › Cowork plugin](#3b-cowork-plugin)
• registerTool migration — modern MCP SDK entrypoint with structured outputSchema on every read tool
• Typo catcher + auto-pageId — fewer "did you mean…" round-trips when there's only one page
• Tighter outputSchema (v0.8.2) — 14 read tools now ship per-tool zod response schemas; mutation tools keep the loose envelope

Full details: [CHANGELOG.md](CHANGELOG.md).

---

What is this?

The first open-source MCP server for Power BI report authoring. It connects Claude (or any MCP-compatible client — see [Tested clients](#tested-clients)) to Power BI's PBIR (Power BI Report) file format, turning natural language into real report pages — cards, charts, tables, themes, filters, and formatting.

No REST API keys. No Power BI service. Just local files + Claude.

You: "Build me a sales dashboard with KPIs, trend charts, and a detail table"

AI:  pbir_create_page → pbir_add_visual (batch: 12 visuals) → pbir_set_report_theme → done.
     Open in Power BI Desktop. ✓

---

Why MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. Instead of the AI generating code for you to run, it directly executes operations through the MCP server.

graph LR
    subgraph AI["AI Assistant"]
        LLM["Claude, GPT,Copilot, Cursor..."]
    end

    subgraph MCP["Two MCP Servers"]
        direction TB
        MODEL["powerbi-modeling-mcpTables, columns, measures, DAX"]
        REPORT["powerbi-report-mcpPages, visuals, themes, filters"]
    end

    subgraph Files["Power BI Project"]
        direction TB
        SEM[".SemanticModelTMDL / measures"]
        REP[".ReportPBIR / visual.json"]
    end

    PBI["Power BIDesktop"]

    LLM |"stdio / MCP"| MODEL
    LLM |"stdio / MCP"| REPORT
    MODEL |"read"| SEM
    REPORT |"read/write"| REP
    REP -->|"open .pbip"| PBI

The typical workflow:

1. Query the model   --> "What tables and measures are available?"    (modeling-mcp)
2. Build the report  --> "Create a dashboard with those measures"     (report-mcp)
3. Open in Desktop   --> Ctrl+Shift+F5 to refresh

> Both servers run simultaneously as MCP tools. The AI queries the semantic model for exact table/column/measure names, then uses those to build correctly-bound report pages — no guessing, no broken fields.

Zero vendor lock-in — built on @modelcontextprotocol/sdk + zod. No Anthropic, OpenAI, or Microsoft SDK imports.

---

How It Compares

| | This MCP Server | Manual PBI Desktop | Power BI REST API | pbi-tools | |---|---|---|---|---| | Input | Natural language | Mouse clicks | REST calls + auth | CLI commands | | Speed | 10-page report in minutes | Hours | Hours (code-heavy) | Minutes (extract/deploy) | | Auth required | None (local files) | None | Azure AD + Service Principal | None | | AI-native | Yes (MCP) | No | No | No | | Format | PBIR (file-based) | PBIX (binary) | Cloud-only | PBIX ↔ folder | | Creates visuals | Yes | Yes | Limited | No (metadata only) | | Themes & formatting | Yes | Yes | Limited | No | | Filters | Yes | Yes | Yes | No | | Works offline | Yes | Yes | No | Yes |

---

Quick Start

> Full walkthrough: [docs/quickstart.md](docs/quickstart.md)

1. Install

git clone https://github.com/jonathan-pap/powerbi-report-mcp.git
cd powerbi-report-mcp
npm install
npm run build

2. Configure your MCP client

Ready-to-use config files are in the [configs/](configs/) folder — copy the one for your client, update the path, done.

| Config | Client | Copy to | |--------|--------|---------| | [claude-desktop.json](configs/claude-desktop.json) | Claude Desktop | %LOCALAPPDATA%\...\Claude\claude_desktop_config.json | | [cursor.json](configs/cursor.json) | Cursor | ~/.cursor/mcp.json | | [vscode-copilot.json](configs/vscode-copilot.json) | GitHub Copilot | .vscode/mcp.json | | [windsurf.json](configs/windsurf.json) | Windsurf | ~/.windsurf/mcp.json | | [continue-dev.json](configs/continue-dev.json) | Continue.dev | ~/.continue/config.json | | [cline.json](configs/cline.json) | Cline | VS Code Settings → MCP Servers |

Claude Code (no config file needed):

claude mcp add powerbi-report-mcp node C:\path\to\powerbi-report-mcp\dist\index.js

> Each config includes both powerbi-report-mcp and powerbi-modeling-mcp for full dual-layer access. See [configs/README.md](configs/README.md) for optional settings (pre-connect to a report, load all tools at startup).

Optional: opt into minimal tool loading

For long Claude Code / Cowork sessions where catalog tokens matter, set MCP_TOOLS=minimal to load only the 12 default tools at startup (saves ~7,500 catalog tokens; the remaining 44 activate on demand via pbir_load_tools):

{
  "mcpServers": {
    "powerbi-report-mcp": {
      "command": "node",
      "args": ["/path/to/powerbi-report-mcp/dist/index.js"],
      "env": {
        "MCP_TOOLS": "minimal"   // optional — saves ~7,500 catalog tokens
      }
    }
  }
}

Trade-off summary (full breakdown in [Smart Tool Loading](#smart-tool-loading) below):

• Default (load-all) — All 56 tools available immediately. Best for unpredictable/exploratory sessions and clients that snapshot the tool list at startup. ~14,500 catalog tokens.
• MCP_TOOLS=minimal — 12 default tools at startup; others activatable via pbir_load_tools. Best for known-narrow workflows. ~7,000 catalog tokens. Requires MCP client support for notifications/tools/list_changed to surface activated tools mid-session — Claude Code/Desktop don't refresh; Cowork may; verify before relying.

3b. Cowork plugin

Prefer to skip the git clone/npm install dance? Grab the latest .plugin bundle from GitHub Releases and drag it into Claude — the plugin ships the server, skills, and a default MCP wiring in one file.

| Step | Action | |------|--------| | 1 | Download powerbi-report-builder-.plugin from the latest release | | 2 | Open Claude → Settings → Plugins → Install from file (or drag-and-drop the .plugin onto the Claude window) | | 3 | Approve the bundled MCP server when prompted | | 4 | In any Claude conversation: "Connect to C:\\Projects\\Sales.Report and list pages" |

> Cowork is a hosted Claude experience with native plugin support. The plugin bundle is a single zip; nothing leaves your machine and the MCP server still runs locally over stdio.

3. Connect and build

Connect to C:\Projects\Sales.Report
Create a page called "Overview" with 4 KPI cards and a bar chart by country

4. Open in Power BI Desktop

Open the .pbip file — or if already open, press Ctrl+Shift+F5 to refresh.

Headless / eval mode

For automated/eval use you can auto-bind a report at startup with the PBIR_REPORT_PATH env var instead of calling pbir_set_report:

PBIR_REPORT_PATH=evals/fixtures/sample.Report node dist/index.js

If the path is invalid the server logs to stderr and continues running unbound (use pbir_set_report to recover). The CLI arg form (node dist/index.js ) still works and wins when both are set.

---

Smart Tool Loading

By default all 56 tools load at startup — this is the most compatible configuration, and what you want for Claude Desktop and most other MCP clients whose tool catalog is a snapshot taken at session start.

For token-sensitive setups (e.g. Claude Code with large prompt budgets on dev machines), you can opt into the minimal mode — only 12 core tools load at startup, and the LLM activates more on-demand via pbir_load_tools:

"env": { "MCP_TOOLS": "minimal" }

graph TD
    subgraph DEFAULT["11 Core Tools — always loaded in both modes"]
        A1[pbir_set_report] --- A2[pbir_list_pages] --- A3[pbir_list_visuals] --- A4[pbir_create_page] --- A5[pbir_add_visual]
        B1[pbir_get_visual] --- B2[pbir_format_visual] --- B3[pbir_update_visual_bindings] --- B4[pbir_set_report_theme] --- B5[pbir_bulk_bind]
        C1[pbir_model_usage]
    end

    LT[pbir_load_tools -- always available]

    subgraph ONDEMAND["43 On-Demand Tools"]
        C1[pbir_delete_page] --- C2[pbir_rename_page] --- C3[pbir_duplicate_page] --- C4[pbir_move_visual] --- C5[pbir_delete_visual]
        D1[pbir_set_datapoint_colors] --- D2[pbir_set_conditional_format] --- D3[pbir_add_page_filter] --- D4[pbir_set_visual_sort] --- D5[guide]
        E1[pbir_list_bookmarks] --- E2[pbir_set_page_background] --- E3[...]
    end

    DEFAULT --> LT --> ONDEMAND

    style DEFAULT fill:#1a7f37,color:#fff
    style ONDEMAND fill:#333,color:#ccc
    style LT fill:#0078D4,color:#fff

| Mode | Tools at Startup | Token Overhead | Use Case | |------|------------------|----------------|----------| | default | 56 + pbir_load_tools | ~16,500 tokens | Claude Desktop, most clients, first-time users | | MCP_TOOLS=minimal | 12 + pbir_load_tools | ~3,400 tokens | Claude Code / clients that refresh the tool list mid-session | | MCP_TOOLS=all (legacy alias) | 56 + pbir_load_tools | ~16,500 tokens | Same as default; kept for backward-compat |

> Default is "load everything" because Claude Desktop snapshots the MCP tool catalog at session start and never refreshes it — tools activated mid-session via pbir_load_tools would otherwise be invisible to the model. Clients that honour tools/list_changed notifications (Claude Code, Cowork) can opt into MCP_TOOLS=minimal to claw back ~13k tokens.

---

Tool Reference

Default Tools

| Tool | Description | |------|-------------| | pbir_set_report | Connect to a .Report folder at runtime | | pbir_list_pages | List all pages (id, name, visual count) | | pbir_list_visuals | List visuals on a page (id, type, position, title) | | pbir_create_page | Create a new page | | pbir_add_visual | Add one or many visuals with bindings, formatting, colors | | pbir_get_visual | Inspect a visual's config and bindings | | pbir_format_visual | Format axes, legend, labels, borders, background | | pbir_update_visual_bindings | Replace data bindings on a visual | | pbir_set_report_theme | Apply a custom JSON theme to the whole report | | pbir_bulk_bind | Rebind multiple visuals in one call | | pbir_model_usage | Cross-reference semantic model with report — three-tier classification (direct/indirect/unused), DAX lineage, UDF functions, conditional formatting detection | | pbir_load_tools | List and activate on-demand tools |

Why pbir_model_usage is a default tool — the deletion fail-safe

pbir_model_usage ships in the default set (not on-demand) because it is the safety layer for AI-driven cleanup of the semantic model. When a user asks Claude to "remove unused measures" or "clean up dead columns", the model would otherwise guess based on measure names and delete things blindly — and break visuals that depend on indirect references.

With pbir_model_usage always available, the LLM can call it first and see the full dependency picture before touching anything:

| Scenario | Without pbir_model_usage | With pbir_model_usage | |---|---|---| | User: "delete all unused measures" | LLM guesses by name, deletes Margin Delta pp, Margin Arrow breaks the next day | LLM sees Margin Delta pp is status indirect (referenced by Margin Arrow), keeps it, lists only the truly safe ones | | User: "is Discount Arrow used anywhere?" | LLM greps the visual JSON, misses conditional formatting bindings | LLM sees it bound to cardImage.imageData / referenceLabel.value and reports exactly where | | User: "which UDF functions can I drop?" | LLM has no lineage info | LLM sees reference counts per function and flags zero-reference functions |

The MCP tool gives Claude that understanding before it mutates anything — what prevents "oops" deletes. The tool returns a slim JSON response (~7K tokens) by default so it's cheap to call before every destructive operation.

On-Demand Tools (43)

Report & Page Management — 17 tools

| Tool | Description | |------|-------------| | pbir_get_report | Show connected report path | | pbir_reload_report | Reopen report in PBI Desktop | | pbir_get_report_settings | Read report-level settings | | pbir_update_report_settings | Merge new report settings | | get_page_summary | All pages + visuals in one call | | pbir_delete_page | Delete a page and its visuals | | pbir_rename_page | Rename a page | | pbir_duplicate_page | Clone a page with all visuals | | pbir_reorder_pages | Set page order | | pbir_set_active_page | Set default page on open | | pbir_update_page_size | Change page dimensions | | pbir_set_page_visibility | Show/hide from navigation | | pbir_auto_layout | Auto-arrange visuals in a grid | | pbir_set_filter_pane | Show/hide and expand/collapse the filter pane | | pbir_set_page_background | Set page canvas background color and/or wallpaper | | pbir_set_visual_interaction | Set cross-filter/highlight interaction between visuals | | pbir_manage_extension_measures | Add, list, or remove report-level DAX measures |

Visual Management — 5 tools

| Tool | Description | |------|-------------| | pbir_delete_visual | Remove a visual | | pbir_duplicate_visual | Clone a visual | | pbir_move_visual | Reposition and resize | | pbir_change_visual_type | Swap type, keep bindings | | pbir_get_visual_types | List all visual types and buckets |

Formatting & Colors — 6 tools

| Tool | Description | |------|-------------| | pbir_set_visual_title | Set title text, font, alignment | | pbir_set_datapoint_colors | Per-series or per-category colors | | pbir_set_conditional_format | Rules-based or gradient formatting | | pbir_set_visual_sort | Set or change sort order (column/measure, ascending/descending) | | pbir_apply_theme | Apply a preset theme to a page | | pbir_audit_theme_compliance | Scan visuals for formatting overrides conflicting with theme |

Themes — 4 tools

| Tool | Description | |------|-------------| | pbir_get_report_theme | Get current theme JSON | | pbir_remove_report_theme | Revert to default theme | | pbir_list_report_themes | List stored theme files | | pbir_diff_report_theme | Compare proposed vs current theme |

Filters — 4 tools

| Tool | Description | |------|-------------| | pbir_list_filters | List page or visual filters | | pbir_add_page_filter | Add categorical, TopN, relative date, or advanced filter | | pbir_remove_filter | Remove a filter by name | | pbir_clear_filters | Remove all filters |

Bulk Operations — 2 tools

| Tool | Descriptio

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jonathan-pap
• Source: jonathan-pap/powerbi-report-mcp
• License: MIT
• Homepage: https://github.com/jonathan-pap/powerbi-report-mcp/releases

Install and usage instructions live in the source repository linked above.