Pbirb MCP

pbirb-mcp

An MCP server for editing Power BI Report Builder paginated reports (.rdl) through Claude (Desktop, CLI, or any MCP client). 140+ tools cover the gaps that otherwise force hand-written XML: report creation, data sources and datasets, calculated fields, dataset and tablix filters, groupings (row, column, matrix), sorting, charts, headers and footers, body composition, layout containers, positioning, styling, page setup, pagination, advanced parameters, embedded images, interactivity (actions, tooltips, document map), transactions, and validation.

The server speaks MCP (JSON-RPC 2.0) over stdio, MCP protocol revisions 2024-11-05 through 2026-07-28. It opens an .rdl from disk, mutates it in place via lxml, validates structure, and writes atomically — a failed save never leaves a half-written report or scrubs the original.

Security defaults. The pbirb-mcp server only opens files under the

directory it was started in, and refuses destructive tools (removals,

convert_to_matrix, raw_xml_replace / raw_xml_remove,

restore_from_backup) until the

call carries confirm=true. MCP clients often start servers in / or in

their own app directory, so **set PBIRB_MCP_ALLOWED_ROOTS to your

reports folder** (see Security defaults).

Stability

Pre-1.0. The tool surface — tool names, inputSchema, output shapes, error semantics — is the contract. While on 0.x, MINOR releases may include a small breaking change with a migration note in CHANGELOG.md; after v1.0, breaking changes require MAJOR. See CONTRIBUTING.md for the full bump rules adapted from SemVer for an MCP tool surface.

Pin to a MINOR while on 0.x (e.g. pbirb-mcp~=0.1) if your prompts depend on specific tool names or schemas.

---

Quick start

1. Install

The simplest path is uv + PyPI — no clone, no venv, no install step:

uvx pbirb-mcp

uvx fetches the package into a throwaway environment, runs the pbirb-mcp console script, and exits. The MCP server speaks JSON-RPC over stdio, so any MCP client (Claude Desktop, Claude Code, etc.) can spawn it directly.

For local development against this codebase instead:

git clone https://github.com/mafaq229/pbirb-mcp

cd pbirb-mcp uv venv .venv uv pip install --python .venv/bin/python -e ".[dev]"

Verify the binary works:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \

| .venv/bin/pbirb-mcp

You should see a single JSON-RPC response with protocolVersion, capabilities.tools, and serverInfo.name = "pbirb-mcp".

2. Wire into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "pbirb": { "command": "uvx", "args": ["pbirb-mcp"], "env": { "PBIRB_MCP_ALLOWED_ROOTS": "/Users/you/Reports" } } } }

Claude Desktop may start the server with its working directory set to / or to the app's own directory, and by default the server only opens files under its working directory — so set PBIRB_MCP_ALLOWED_ROOTS to the folder(s) holding your reports (on Windows e.g. "C:\\Users\\you\\Reports"; separate several with : on macOS/Linux, ; on Windows). See Security defaults.

Restart Claude Desktop. The hammer icon should show pbirb and the 140+ tools listed below.

To enable file logging, add PBIRB_MCP_LOG_FILE to the env block — but keep it platform-appropriate: it takes an OS-native path, so a Unix path like /tmp/pbirb-mcp.log only works on macOS/Linux. On Windows use a Windows path (e.g. %TEMP%\\pbirb-mcp.log). See Logging. When unset, logs go to stderr, which Claude Desktop captures in its MCP debug pane on every platform.

For development against a local checkout, swap the args for ["--from", "/absolute/path/to/pbirb-mcp", "pbirb-mcp"] so uvx runs your working tree instead of the published version.

3. Wire into Claude Code

claude mcp add pbirb -- uvx pbirb-mcp

Or add to .mcp.json at the workspace root:

{

"mcpServers": { "pbirb": { "command": "uvx", "args": ["pbirb-mcp"] } } }

Or install it as a Claude Code plugin — one command instead of editing config by hand (it wires up the same uvx pbirb-mcp server for you):

/plugin marketplace add mafaq229/pbirb-mcp

/plugin install pbirb-mcp@pbirb

4. Smoke test

In any chat, ask the model:

Open ~/path/to/some-report.rdl and tell me what datasets and parameters it has.

The model should call describe_report, get_datasets, and get_parameters and summarise the result. If it doesn't, your client probably hasn't loaded the server — check the client's MCP debug log.

---

Configuration

Security defaults

The pbirb-mcp command (what MCP clients launch) is locked down by default:

• File access is limited to the working directory. Every path argument (path and every *_path) must resolve — symlinks and .. followed — inside an allowed root, or the call is refused with PathNotAllowed before anything is read or written. Set PBIRB_MCP_ALLOWED_ROOTS to the directories to allow (os.pathsep-separated: : on macOS/Linux, ; on Windows); * means unrestricted. Clients such as Claude Desktop may start the server in / or their app directory, so set it explicitly (see the config example in the Quick start).
• Destructive tools need `confirm=true`. Tools that delete report content or overwrite a file (every remove_*, convert_to_matrix, raw_xml_replace / raw_xml_remove, restore_from_backup, and an apply_edits batch that contains one) are refused with ConfirmationRequired until the call carries confirm=true; 2026-07-28 clients that support elicitation are asked to confirm instead. PBIRB_MCP_REQUIRE_CONFIRM=0 turns this off.
• Audit log (opt-in). PBIRB_MCP_AUDIT_LOG=/path/to/audit.jsonl appends one JSON line per edit and per transaction commit.

An MCPServer embedded in Python (tests, the eval harness, library use) defaults to unrestricted roots and no confirmation; the same environment variables opt it in.

Toolsets and read-only mode

By default the server lists every tool. To give the model fewer tool definitions to read (and fewer to choose from), enable only the toolsets a task needs, and/or run read-only:

{

"mcpServers": { "pbirb": { "command": "uvx", "args": ["pbirb-mcp", "--toolsets", "data,parameters", "--read-only"] } } }

• --toolsets takes comma-separated names, all, or default (PBIRB_MCP_TOOLSETS sets the same; the flag wins). Unknown names are an error. pbirb-mcp --list-toolsets prints every toolset's tools.
• --read-only (or PBIRB_MCP_READ_ONLY=1) exposes only tools published with readOnlyHint: true — readers, validation, expression helpers and dry_run_edit, which previews an edit on a temp copy.
• The limits are enforced when a tool is *called*, not only in tools/list: a call outside the enabled toolsets, or an edit in read-only mode, returns an isError result (ToolNotEnabled / ReadOnlyMode) naming the setting to change. apply_edits / dry_run_edit ops are held to the same toolsets.

Every tool also carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint: false) and a display title, so clients can auto-approve the readers and flag the destructive tools.

Environment variables

Truthy values are 1, true, yes, on (case-insensitive).

Logging

PBIRB_MCP_LOG_LEVEL=DEBUG PBIRB_MCP_LOG_FILE=/tmp/pbirb-mcp.log pbirb-mcp

---

Working with a report

The recommended flow is read first, then edit by name. Every mutating tool addresses elements by their RDL Name attribute (Tablix name, Textbox name, ReportParameter name, DataSet name) — never by index. Indices break across multi-step edits.

A typical session:

You:    Bind the existing report at ~/Reports/sales.rdl to the Finance

workspace's "FY26 Sales" dataset, change the body DAX to a date- ranged query, and add a header with a logo and a parameter line.

Claude: → describe_report(path=…) → set_datasource_connection(name="PBIDataset", workspace_url="Finance", dataset_name="FY26 Sales") → update_dataset_query(dataset_name="MainDataset",