powerbi-report-mcp

An MCP server for reading and editing the report/visual layer of Power BI PBIP projects — pages, visuals, field bindings, formatting, and themes — directly on disk, so AI assistants can build and restyle reports alongside you.

It pairs with Microsoft's official powerbi-modeling-mcp (semantic model: tables, measures, relationships); this server deliberately never touches the semantic model.

Features

• 37 tools covering connections, pages, visuals, field wells, format patching, themes, report settings, and style profiles.
• Implicit active report — connection_name is optional on every tool; the most recently opened/used report is the default target.
• Git-style undo — every edit is snapshotted per connection; undo() rolls back one step at a time (no redo), and list_history() shows the undo stack.
• Atomic writes — files are written via temp-file rename so Power BI Desktop never sees a half-written JSON file.
• Schema-validated models — Pydantic models mirror Microsoft's published PBIP JSON schemas, with a discriminated union per visual family.
• Style profiles — capture fonts, colours, borders, and canvas size in a reusable JSON profile and distil it into a report, page, or single visual with apply_style; only the parts relevant to the scope are applied.
• Extension visual types — register custom/AppSource visuals at runtime with the register_visual_extension tool; usable immediately, no restart.
• stdio and HTTP transports — spawned per client (stdio, default) or one instance serving many clients via --transport http, with each client in its own isolated session.

Quick start

Requires uv (Python 3.12+ is fetched automatically). Two officially supported ways to run it:

Usage — PyPI, stdio (recommended for normal use):

{
  "powerbi-report-mcp": {
    "type": "stdio",
    "command": "uvx",
    "args": ["powerbi-report-mcp"]
  }
}

Development — local clone, HTTP (for working on the server itself, with live edits and no rebuild step). Run it yourself in a terminal, on a port you pick:

git clone https://github.com/mattbeard0/powerbi-report-mcp.git
cd powerbi-report-mcp
uv run powerbi-report-mcp --transport http --port 8731

...then point your client at http://127.0.0.1:8731/mcp — a custom connector for Claude Desktop, an mcpServers "url" entry for clients that support it directly. This is also the route to remote-only clients like ChatGPT, and to serving several clients from one process (each gets its own isolated session — connections and undo history — touching the same report only when each explicitly opens it).

Avoid running uv run powerbi-report-mcp as a stdio command on Windows — the extra uv.exe process layer can stall the client's connect handshake (confirmed with Claude Desktop and MCP Inspector); use HTTP instead.

Then in your assistant: "Open C:/Projects/MyReport.Report and add a card visual showing Total Sales."

docs/installation.md has copy-paste setup for Claude Desktop, Claude Code, Codex / Codex CLI, ChatGPT, VS Code, and Cursor — each from PyPI or from a local folder — plus the Microsoft modeling MCP.

Development

uv sync                                  # includes the dev dependency group
uv run pytest                            # unit tests (network tests excluded)
uv run pytest -m network                 # live schema-conformance tests
uv run ruff check src tests
uv run mypy src

License

MIT