horizun-pbi-mcp

# Horizun PBI MCP [](https://github.com/HorizunGroup/horizun-pbi-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/horizun-pbi-mcp/) [](https://pypi.org/project/horizun-pbi-mcp/) [](LICENSE) **Build and fix Power BI reports by describing what you want.** Ask in plain language; the server runs the DAX, edits the model, writes the report pages — and checks its own work afterwards. ### No licence, no API key, no paid plan It runs as a **local process on your own Windows machine**, so the free apps are enough: install it in **ChatGPT Desktop** or **Claude Desktop** on their free tiers and start asking. No OpenAI or Anthropic API key, no subscription, no server of ours in the middle — and Power BI Desktop is free as well. One click installs it and it prepares its own runtime: no Python, no JSON to edit.  **v2.1.1** · 139 tools · Windows · ChatGPT Desktop Free · Claude Desktop Free · Claude Code · Codex New to the project? Start with [what this Power BI MCP is, when to use it, and what it deliberately does not do](docs/POWER_BI_MCP.md). ## Install No repository clone, manual DLL download or `.mcp.json` editing is required. Pick the line that matches you. ### ChatGPT Desktop Free Run the verified one-paste installer from [`docs/INSTALL.md`](docs/INSTALL.md), restart ChatGPT Desktop, then open **Plugins → Personal** and install **Horizun PBI MCP**. No OpenAI API key is required. ### Claude Desktop Free Download the `.mcpb` from the [latest release](https://github.com/HorizunGroup/horizun-pbi-mcp/releases/latest) and double-click it. Claude Desktop supplies the bootstrap runtime; no Claude Code install or JSON editing is required. It will say the extension is **not verified by Anthropic** — what it says about anything installed outside its own directory — and let you continue. ### Claude Code ```powershell claude plugin marketplace add HorizunGroup/horizun-pbi-mcp claude plugin install horizun-pbi-mcp@horizun ``` ### Codex ```powershell codex plugin marketplace add HorizunGroup/horizun-pbi-mcp ``` Then open `/plugins`, pick the **Horizun** marketplace and install `horizun-pbi-mcp`. ### Desktop or Code? Same server, same 139 tools, same local runtime — install both and they share it. Pick by what you are doing: **Claude Desktop** to *use* Power BI, in chat, one click, free tier. **Claude Code** to *build* — it adds the terminal, git and your repo, and loads tool schemas on demand instead of all at once. On a new PC, the [verified one-paste installer](docs/INSTALL.md) prepares the prerequisites without administrator rights. First setup takes a few minutes: run `pbi_install_status` until `ready`, restart once, and confirm the 139 `pbi_*` tools appear. ## Your first minute 1. Open Power BI Desktop with any report. 2. Ask: *"List the Power BI models that are open and connect to the first one."* 3. Ask: *"Run a read-only DAX query that returns revenue by month for this year."* If step 2 answers, everything works. ## Things worth asking for ```text Audit this PBIP project and explain the highest-risk issues before changing anything. ``` ```text This measure returns blank for December. Find out why. ``` ```text Create a report page from this specification, validate it, and show me the layout. ``` ```text Document every measure in the model and export it to Excel. ``` ## What it provides | Area | Capabilities | |---|---| | Live model | Discover Desktop sessions, run DAX, inspect metadata, refresh, and manage measures through TOM | | Semantic model | Read and edit TMDL tables, columns, measures, relationships, roles and calculation groups | | Report authoring | Create pages and visuals, clone templates, arrange layouts, apply themes, bookmarks and interactions | | Conversion | Convert `.pbix` to `.pbip`, migrate supported structures and validate the result | | Quality | Audit models and reports, document schemas, detect broken references and normalize report structures | | Delivery | Export verified PDF, Word, Excel and PowerPoint artifacts; ingest SharePoint data read-only | See the [tool catalog](docs/TOOL_CATALOG.md) for all 139 tools and their risk classifications. ## Why it is safe to point at real work - Local-first: Power BI Desktop communication stays on `localhost`. - No telemetry, and the MCP server needs no account. - Project writes stay inside the active project directory. - Every project write makes a backup and is re-read to confirm it landed. - Destructive tools require `confirm=true`. - JSON writes are atomic; invalid JSON is never written over good JSON. - Downloaded runtime components are version-pinned and SHA-256 verified. - Logs go to stderr or files, so stdout stays a clean JSON-RPC channel. Full guarantees and failure behavior: [security model](docs/SECURITY.md) and [recovery guide](docs/RECOVERY.md). Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). ## Requirements - Windows 10 or 11. - Python 3.10 or newer. - Power BI Desktop — only for the live layer (DAX, refresh, capture, render checks). - A `.pbip` project with PBIR enabled, for report-file authoring. - Node.js 20+ only for the optional Microsoft PBIR validator. Claude Code, Codex and Power BI Desktop are external programs; this project does not install them. Without Desktop the `.pbip` tools still work — the live tools do not. ## Known limits - Power BI does not expose pages or visuals through its live local endpoint, so those are edited in PBIR files while Desktop is safely closed. - `mode="both"` is disabled for dual live/disk writes: Desktop being open and a PBIP project being safe to edit are mutually exclusive states. - The server does not publish to or refresh the Power BI Service. - Three PBIR schemas referenced by Power BI are not published by Microsoft; affected writes fail closed instead of guessing. ## Documentation | Document | Purpose | |---|---| | [Installation](docs/INSTALL.md) | Setup, repair, offline installation and MCP client registration | | [Tutorial](docs/TUTORIAL.md) | First connection through report authoring | | [Power BI MCP overview](docs/POWER_BI_MCP.md) | Use cases, boundaries, safety and first workflow | | [Tool catalog](docs/TOOL_CATALOG.md) | All tools, grouped by capability and risk | | [Architecture](docs/ARCHITECTURE.md) | Components, boundaries and invariants | | [Security](docs/SECURITY.md) | Threat model and operational guarantees | | [Validation](docs/VALIDATION.md) | TMDL/PBIR validation layers and known limits | | [Migration guide](docs/MIGRACION_1x_A_2.0.md) | Breaking changes from 1.x to 2.0 | | [Contributing](CONTRIBUTING.md) | Development workflow and pull-request requirements | ## Development ```powershell git clone https://github.com/HorizunGroup/horizun-pbi-mcp.git cd horizun-pbi-mcp python -m pip install -e . python scripts/fetch_libs.py python scripts/fetch_pbir_schemas.py python scripts/doctor.py ``` Before opening a pull request: ```powershell python -m pytest -q python scripts/doctor.py python -m tests.contract_utils ``` The MCP contract is frozen and checked against `tests/golden/tools_v1.json`. Real `.pbix`, `.pbip`, credentials, DLLs, outputs and backups are never committed. See [AGENTS.md](AGENTS.md) for the repository invariants. ## License Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). ## MCP Registry This package is the one published under the server name below. The registry reads this line from the README of the **PyPI package** to confirm that whoever publishes the metadata also owns the package, so it has to live here rather than in `.mcp/server.json` alone. ``` mcp-name: io.github.HorizunGroup/horizun-pbi-mcp ```