pbirb-mcp
pbirb-mcp is an MCP server for safely inspecting, validating, and editing Power BI Report Builder paginated reports (.rdl) over JSON-RPC/stdio.
Inspect reports: inventory data sources, datasets, parameters, tablixes/charts, filters, fields, textboxes/images/rectangles/charts, and body/header/footer items.
Edit data and datasets: update DAX queries, manage query parameters, dataset fields/calculated fields, dataset filters, and Power BI XMLA data sources.
Edit tablix/layout: row/column groups, columns, static rows/columns, subtotals, filters, sorting, visibility, spans, sizes, matrices, rectangles, lists, lines, and positioning/resizing.
Manage parameters, charts, images, actions, tooltips, document-map labels, page breaks, pagination hints, and headers/footers.
Validate and preview changes: validate/verify/lint, dry-run diffs, transactions, atomic batch edits, backups/restore, duplicate/create reports, expression helpers, and raw XML view/replace.
Apply safety controls from the server: allowed roots, destructive-call confirmation, read-only mode/toolsets, audit logging, auto-verify, and auto-backup.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pbirb-mcp Open ~/Reports/sales.rdl and list its datasets and parameters."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpserver 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 carriesconfirm=true. MCP clients often start servers in/or in their own app directory, so setPBIRB_MCP_ALLOWED_ROOTSto 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.
Related MCP server: Power BI MCP for Claude
Quick start
1. Install
The simplest path is uv + PyPI — no clone, no venv, no install step:
uvx pbirb-mcpuvx 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-mcpYou 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-mcpOr 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@pbirb4. Smoke test
In any chat, ask the model:
Open
~/path/to/some-report.rdland 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 (
pathand every*_path) must resolve — symlinks and..followed — inside an allowed root, or the call is refused withPathNotAllowedbefore anything is read or written. SetPBIRB_MCP_ALLOWED_ROOTSto 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 (everyremove_*,convert_to_matrix,raw_xml_replace/raw_xml_remove,restore_from_backup, and anapply_editsbatch that contains one) are refused withConfirmationRequireduntil the call carriesconfirm=true; 2026-07-28 clients that support elicitation are asked to confirm instead.PBIRB_MCP_REQUIRE_CONFIRM=0turns this off.Audit log (opt-in).
PBIRB_MCP_AUDIT_LOG=/path/to/audit.jsonlappends 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"]
}
}
}Toolset | Covers |
| Always on: |
| Data sources, datasets, DAX queries, query parameters, fields, dataset filters |
| Report parameters: declarations, available/default values, prompts, pane layout |
| Tables and matrices: groups, columns, rows, subtotals, spans, filters, sorting, group visibility, pagination |
| Charts: series, axes, legend, data labels, palette, colours, title |
| Textbox text and formatting, finding textboxes, row styling |
| Page setup, body/header/footer items, positions and sizes, containers, images, embedded images, element visibility |
| Actions (links, drill-through, bookmarks), tooltips, document map |
|
|
--toolsetstakes comma-separated names,all, ordefault(PBIRB_MCP_TOOLSETSsets the same; the flag wins). Unknown names are an error.pbirb-mcp --list-toolsetsprints every toolset's tools.--read-only(orPBIRB_MCP_READ_ONLY=1) exposes only tools published withreadOnlyHint: true— readers, validation, expression helpers anddry_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 anisErrorresult (ToolNotEnabled/ReadOnlyMode) naming the setting to change.apply_edits/dry_run_editops 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
Variable | Default | Purpose |
|
| Directories report paths must be inside ( |
|
| Destructive tools need |
| off | File to append one JSON line to per edit and per transaction commit. |
| every toolset | Comma-separated toolsets to expose ( |
| off |
|
| off |
|
|
| Seconds an editing transaction lives without a commit or cancel; an expired one is discarded (nothing saved). |
|
|
|
| stderr | Log file path (see Logging). |
| off |
|
Truthy values are 1, true, yes, on (case-insensitive).
Logging
Variable | Default | Purpose |
|
|
|
| stderr | Path to a log file; otherwise logs go to stderr (where Claude Desktop captures them in its MCP debug pane) |
PBIRB_MCP_LOG_LEVEL=DEBUG PBIRB_MCP_LOG_FILE=/tmp/pbirb-mcp.log pbirb-mcpWorking 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",
dax_body="EVALUATE FILTER('Sales',
'Sales'[OrderDate] >= @DateFrom &&
'Sales'[OrderDate] <= @DateTo)")
→ add_query_parameter(dataset_name="MainDataset",
name="DateFrom",
value_expression="=Parameters!DateFrom.Value")
→ add_query_parameter(dataset_name="MainDataset",
name="DateTo",
value_expression="=Parameters!DateTo.Value")
→ add_embedded_image(name="Logo",
mime_type="image/png", image_path="~/brand/logo.png")
→ set_page_header(height="0.75in",
print_on_first_page=True, print_on_last_page=True)
→ add_header_image(name="HeaderLogo",
image_source="Embedded", value="Logo",
top="0in", left="0in", width="1in", height="0.5in")
→ add_header_textbox(name="DateLine",
text='="From: " & Parameters!DateFrom.Value & " To: "
& Parameters!DateTo.Value',
top="0.1in", left="1.2in", width="4in", height="0.25in")Open the resulting .rdl in Report Builder; the change is visible in the
designer and renders in Preview against the bound dataset.
Tool reference
The tools, grouped by RDL concern. The highlights of each group are tabled
below; the authoritative, always-current list with full schemas is the
server's tools/list output (pbirb-mcp --list-toolsets prints the names by
toolset), and docs/TOOLS.md has every tool's full behaviour
notes. Every report tool takes a path argument (absolute path to the
.rdl).
Every tool that takes a report path also accepts an optional
transaction_id, so a multi-step edit batches into a single atomic save —
see Transactions and
docs/TRANSACTIONS.md.
Read-only inventory
The "what's in this report?" tools. Always the first calls when planning a multi-step edit.
Tool | Returns |
| Top-level inventory: data sources, datasets, parameters, tablixes, page setup |
| Full DAX command text, fields, query parameters, dataset filters (all, or one by name) |
| Data source inventory; one source's connection details |
| Report parameters with data type, prompt, and flags (multi-value, hidden, nullable, allow-blank) |
| Tablix layout: columns, row/column groups, sort expressions, filters, visibility |
| Filters in document order with stable indices |
| Named report items in each region |
| Full properties of a named report item |
| Embedded image names + MIME types; base64 bytes of one |
| Cheat-sheet of common RDL expression patterns ( |
Datasource & dataset
Tool | What it edits |
| Repoint a |
| Manage |
| Replace |
| Append |
| Change the value expression of an existing query parameter |
| Drop a query parameter (and clean up empty |
| Manage |
| Manage |
| Re-derive the |
| Filters applied at the dataset level (vs. tablix) |
| Manage |
| Point a dataset at another data source; query timeout, collation and case/accent/kana/width sensitivity |
| Rename a field (rewriting |
Tablix
Tool | What it edits |
| Append a |
| Remove by ordinal index from |
| Wrap the row hierarchy in a new outer group + header row (and its inverse) |
| Same, on the column axis |
| Promote a table to a matrix (row + column groups) — see docs/MATRIX-cookbook.md |
| Set the matrix corner cell text/expression |
| Replace |
| Set |
| Set |
| Add/drop a column across the tablix grid |
| Insert a non-grouped row/column |
| Insert an aggregate row/column on a group |
| Set |
| Set |
| Set the tablix's overall |
| Repeat the column header rows on every page |
Page
Tool | What it edits |
| Page dimensions, margins, columns. All fields optional. |
| Swap PageHeight/PageWidth to match |
Page header & footer
Same set of operations for each region, each accepts named items so follow-up edits don't drift on indices.
Tool | What it edits |
| Section height + |
| Append a Textbox (static text or |
| Append an Image (External URL, Embedded name, or Database expression) |
| Remove by name; tidies empty |
Body composition
Tool | What it edits |
| Append a Textbox to |
| Append an Image to the body |
| Remove a named report item from the body; refuses while other items still reference it unless |
| Rename a report item or group and rewrite every reference to it |
Snippet templates
Single-call inserts of common report items, programmatically built and appended to the body.
Tool | What it builds |
| A basic Tablix mirroring the fixture's shape — header row with the column name as a static label, detail row binding to |
| A basic Column chart: single category axis grouped by |
Charts
Refine a chart after insert_chart_from_template (or any existing <Chart>).
Tool | What it edits |
| Manage Y-axis |
| Column / Bar / Line / Area / Pie / ... per series |
| Category/series grouping expression |
| Category / value axis title, scale, format |
| Legend visibility and placement |
| Toggle and format data labels |
| Chart title text/expression |
| Any of the 16 RDL palettes or custom colours; explicit per-series or per-point colour |
| Legend entry, secondary axis, chart area, order, tooltip, markers, empty points of one series |
| Edit a category group's label, sort or field, or add a nested level |
Styling
Tool | What it edits |
| Routes properties to the right nested |
| Apply one style to many textboxes in a single call |
| Copy one textbox's formatting onto others |
| Rich multi-run paragraph content; or replace the value |
| Locate textboxes to target follow-up edits |
| Style every cell of a tablix row at once (header / detail / footer) |
| Zebra-stripe a tablix's detail row with |
| Drive detail-row |
| Image |
Visibility
Tool | What it edits |
| Set |
Layout containers
Tool | What it builds |
| A |
| A list region (single-column tablix template) |
| A |
| Remove a rectangle, moving its items out to its container in place |
Positioning & sizing
Move and resize named items in each region. Coordinates are RDL sizes
("1in", "2.5cm", ...).
Tool | What it edits |
|
|
|
|
| The |
| Move an item between the body, header, footer and rectangles; centre it in its container; fix a body wider than the page |
Interactivity
Tool | What it edits |
|
|
| The same, on any Textbox / Image / Rectangle / Line |
|
|
|
|
|
|
Pagination
Tool | What it edits |
|
|
| Repeat a group header/footer on each page |
| Keep-together rendering hints |
Parameters (advanced)
Tool | What it edits |
| Manage |
| Prompt text; data type (Boolean / DateTime / Integer / Float / Text) |
| Static |
| Static |
| Toggle the four boolean flags: |
| Reorder |
| Position parameters in the |
Cascading parameters
RDL has no <DependsOn> element — cascading is inferred from
=Parameters!X.Value references in a lookup dataset's <QueryParameters>.
To wire parameter B to depend on parameter A:
set_parameter_available_values(name="B", source="query", query_dataset="LookupB", ...)add_query_parameter(dataset_name="LookupB", name="@A", value_expression="=Parameters!A.Value")
Report Builder figures out the dependency graph by parsing those expressions.
Embedded images
Tool | What it edits |
| Read a real file off disk, base64-encode it, store under |
| Names + MIME types |
| Remove by name; tidies empty |
Reference an embedded image with
add_*_image(image_source="Embedded", value="<image-name>").
Report lifecycle
Tool | What it does |
| Scratch-create a minimal valid |
| Copy a report to a new path |
| Snapshot a report (optional folder and label), list its backups and roll back to one (set |
Expression helpers
These don't mutate the report — they build correct RDL expression strings to pass into other tools (text, filters, conditional styling).
Tool | What it returns |
| A |
| An |
| A reference sheet of common RDL expression patterns |
Transactions & validation
Batch many edits into one atomic save, and check correctness before/after.
Tool | What it does |
| Open an in-memory transaction, verify (XSD + lint, new errors only) and save once, or discard. See docs/TRANSACTIONS.md. |
| Apply a list of tool calls in one transaction |
| Preview an edit's effect without writing to disk |
| Semantic diff of a report against a baseline (added / removed / changed items, ignoring layout noise) |
| Structural + XSD validation against the bundled |
| Surface warnings/errors Report Builder would flag |
Raw XML escape hatch
Tool | What it does |
| Read the XML under an XPath |
| Replace the XML at an XPath — last resort for anything without a dedicated tool |
| Insert XML at an XPath; remove the node(s) it matches |
Power BI specifics
XMLA connection strings
set_datasource_connection writes the canonical form:
Data Source=powerbi://api.powerbi.com/v1.0/myorg/<workspace>;Initial Catalog=<dataset>workspace_url accepts a bare workspace name (Finance) or a full
powerbi:// URL — the tool detects the latter and avoids double-prefixing.
DataProvider is set to SQL (the Analysis Services provider id RDL uses
for PBI XMLA, despite the misleading name).
DAX queries
DAX bodies are accepted verbatim — pbirb-mcp doesn't parse DAX, so the
user (or Report Builder at preview time) is the source of truth for syntax.
Empty bodies are rejected up front because Report Builder loads them but
errors at preview, which is a worse signal than a clear ValueError here.
PBI paginated reports do not carry <CommandType> for DAX (unlike
SSRS where you'd set CommandType=StoredProcedure); these tools never
emit it.
Pre-commit hooks (contributors)
pre-commit is in the [dev] extras. After a fresh checkout:
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/pre-commit install # one-time — installs the git hook
.venv/bin/pre-commit run --all-files # one-time — clean any driftAfter the hook is installed, every git commit runs ruff format +
ruff check (with --fix) + the fast pytest suite. If lint or tests
fail the commit is aborted; fix and re-stage before retrying.
To run individual hooks ad-hoc:
.venv/bin/pre-commit run ruff --all-files
.venv/bin/pre-commit run ruff-format --all-files
.venv/bin/pre-commit run pytest-fast --all-filesThe full config lives in .pre-commit-config.yaml. Ruff settings
(line length, rule selection, per-file ignores) live under
[tool.ruff*] in pyproject.toml.
Report Builder install
Power BI Report Builder is a free Microsoft-distributed Windows app:
https://www.microsoft.com/en-us/download/details.aspx?id=105942
Open any .rdl produced by pbirb-mcp directly in Report Builder. The
"opens cleanly with no upgrade prompt" check is the actual integration
test — the unit tests verify schema correctness, but lxml will
round-trip XML that Report Builder's deserialiser still rejects (we hit
this twice in the chart-template work; both fixes are documented in the
git history).
Architecture
pbirb-mcp/
├── pbirb_mcp_server.py # Entry point (CLI flags, logging, main())
├── pbirb_mcp/
│ ├── protocol.py # MCP protocol on the official SDK (stdio, versions)
│ ├── server.py # Tool registry + dispatcher, annotations
│ ├── tools.py # Tool definitions — wires ops into the server
│ ├── core/
│ │ ├── security.py # Allowed roots, confirmation, audit log
│ │ ├── toolsets.py # Toolsets + read-only mode
│ │ ├── document.py # RDLDocument: open/save (lxml), atomic write
│ │ ├── xpath.py # Namespace-aware XPath helpers
│ │ ├── ids.py # Stable element addressing
│ │ ├── encoding.py # XML declaration / self-closing-tag fidelity
│ │ ├── transactions.py # In-memory transaction registry
│ │ └── schema.py # Structural + opt-in XSD validation
│ ├── ops/ # One module per RDL concern; wired into tools.py
│ │ ├── reader.py # describe / get_datasets / get_params / get_tablixes
│ │ ├── datasource.py # PBI XMLA connection + data-source management
│ │ ├── dataset.py # DAX body, query params, fields, calc fields, filters
│ │ ├── tablix.py # Row/column groups, sort, visibility, matrix
│ │ ├── tablix_columns.py # Add/remove tablix columns
│ │ ├── tablix_cells.py # Cell span
│ │ ├── tablix_static.py # Static rows / columns
│ │ ├── tablix_subtotals.py # Subtotal rows / columns
│ │ ├── chart.py # Chart series, axes, legend, labels, palette
│ │ ├── page.py # Page setup + orientation
│ │ ├── layout.py # Pagination (page breaks, keep-together, repeat)
│ │ ├── header_footer.py # Page header / footer authoring
│ │ ├── body.py # Body textboxes / images / containers / removal
│ │ ├── positioning.py # Move / resize named items per region
│ │ ├── templates.py # Chart + tablix snippet builders
│ │ ├── styling.py # Textbox styles, runs, bulk, row styling, find
│ │ ├── images.py # Image sizing / source
│ │ ├── actions.py # Actions, tooltips, document-map labels
│ │ ├── visibility.py # Element-level visibility
│ │ ├── parameters.py # Lifecycle, values, advanced flags, layout
│ │ ├── embedded_images.py # Base64 image embedding
│ │ ├── expressions.py # Expression-builder helpers (count/sum/iif)
│ │ ├── filter_types.py # Filter operator definitions
│ │ ├── clone.py # duplicate_report
│ │ ├── scratch.py # create_report
│ │ ├── snapshot.py # backup / restore
│ │ ├── transactions.py # start/commit/cancel + apply_edits
│ │ ├── dry_run.py # dry_run_edit
│ │ ├── validate.py # validate / verify
│ │ ├── lint.py # lint_report
│ │ └── escape.py # raw_xml_view / raw_xml_replace
│ └── schemas/ # Bundled RDL 2016 XSD (reportdefinition.xsd) for opt-in validation
└── tests/
├── fixtures/
│ └── pbi_paginated_minimal.rdl # Hand-tuned to match Report Builder's emitted style
└── test_*.py # every tool plus round-trip invariantsHard rules (enforced by tests)
Tests first. Every commit writes failing tests, then makes them pass.
lxml, not stdlib
xml.etree. Round-trip fidelity is a feature, not polish. Report Builder reads what's on disk; formatting drift causes silent corruption.Stable IDs, never indices. Tools take
tablix_name+group_name, notcolumn_index: 2. Indices break across multi-step edits.Atomic save. Every write goes to a temp file next to the report and is renamed over it (
core.document.write_atomic), following symlinks and keeping the file's mode. A failure mid-write never leaves a half-written report.Round-trip byte-identity is enforced by
tests/test_byte_fidelity.py(BOM × CRLF × trailing-newline matrix, Report Builder'sMustUnderstandroot and<Style></Style>form) andtests/test_document.py. A no-op open → save → reopen produces a byte-identical file, and a one-value edit changes one line.
RDL gotchas learned the hard way
<?xml version="1.0" encoding="utf-8"?>uses double quotes, not lxml's default single quotes. Fixed inRDLDocument.save_asvia a manual declaration.Self-closing tags use
<Tag />with a space, not<Tag/>. Fixed via a post-process regex.The
rd:prefix (http://schemas.microsoft.com/SQLServer/reporting/reportdesigner) carries designer metadata Report Builder relies on. Don't strip it; preserve prefixes.Do not put
MustUnderstand="df"on<Report>unless you also declarexmlns:df=....<ChartCategoryAxes>/<ChartValueAxes>hold<ChartAxis>children directly — there is no<ChartCategoryAxis>/<ChartValueAxis>wrapper.<ChartMember>requires a<Label>child, even an empty one.DAX queries live in
<DataSet><Query><CommandText>EVALUATE ...</CommandText></Query></DataSet>. No<CommandType>element for DAX (unlike SSRS).
Development
Running tests
.venv/bin/python -m pytest tests/ -vThe suite is fast (well under a minute) so re-run on every change.
Smoke testing the live binary
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| .venv/bin/pbirb-mcpFor an end-to-end sanity check, drive an actual mutation against a copy of the bundled fixture:
SCRATCH=$(mktemp -d)/r.rdl
cp tests/fixtures/pbi_paginated_minimal.rdl "$SCRATCH"
.venv/bin/python -c "
from pbirb_mcp.ops.dataset import update_dataset_query
update_dataset_query(path='$SCRATCH', dataset_name='MainDataset',
dax_body=\"EVALUATE TOPN(10, 'Sales')\")
print('Wrote', '$SCRATCH')
"Open the resulting file in Power BI Report Builder. Manual verification
that an .rdl opens cleanly is the actual integration test — the unit
tests catch schema-level mistakes, but only Report Builder catches
deserialiser nits.
Adding a new tool
Write tests first under
tests/test_*.py.Implement in the appropriate
pbirb_mcp/ops/*.pymodule (or create a new one).Register in
pbirb_mcp/tools.pywith a shortdescription(purpose first, at most 400 characters, no release history — longer notes go in docs/TOOLS.md) and a strictinputSchema; add it to a toolset inpbirb_mcp/core/toolsets.py.Run the full suite and a JSON-RPC smoke against the fixture.
Open the modified RDL in Report Builder.
The commit-by-commit history shows the pattern in practice.
Releases
CHANGELOG.md tracks every release in Keep a Changelog format. Releases are also published as GitHub Releases and to PyPI.
Versions follow SemVer adapted for an MCP tool surface — see CONTRIBUTING.md § Versioning.
Contributing
PRs welcome. CONTRIBUTING.md covers dev setup, the hard rules (tests-first, lxml only, stable IDs, atomic save, byte-identity round-trip, smoke in Report Builder), the SemVer-for-MCP bump table, and the PR review checklist.
Bug reports and tool proposals: please use the issue templates. For security issues, see SECURITY.md. All participants are expected to follow the Code of Conduct.
Acknowledgments
The existing bethmaloney/rdl-mcp server pioneered the MCP-over-RDL pattern but is scoped to SSRS: column metadata, basic parameter management, stored-procedure swap. Power BI paginated reports use the same RDL 2016 schema as SSRS, but:
Data sources are Power BI XMLA endpoints, not SQL Server.
Queries are DAX, and the upstream tool exposes no body-edit (only stored-procedure name swap, useless here).
Report Builder is picky about XML round-tripping — formatting drift, namespace prefix loss, or unrecognised
MustUnderstandattributes cause silent corruption or "this report needs to be upgraded" prompts.
pbirb-mcp is built around lxml so a no-op edit produces a byte-identical
file, addresses every element by stable name (never index), and treats
"opens cleanly in Report Builder" as the actual integration test.
mcp-name: io.github.mafaq229/pbirb-mcpAvailable Tools
143 toolsadd_body_imageB
Add an Image to /. image_source: External (URL), Embedded (EmbeddedImage Name), Database (=Fields!Photo.Value).
Inputs: top (required), left (required), name (required), path (required), +4 more.
add_body_textboxA
Add a Textbox to /. text accepts static strings or RDL expressions (e.g. =Globals!ReportName). Coexists with the existing tablix; rejects names already in use. Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).
Inputs: top (required), left (required), name (required), path (required), +3 more.
add_calculated_fieldA
Append a calculated to the named dataset. Calculated fields carry an expression () instead of a column reference (); use them for derived fields like Total = Amount * Quantity that aren't in the source query but should be available via Fields!Name.Value. Refuses if a field of the same name already exists.
Inputs: path (required), expression (required), field_name (required), dataset_name (required).
add_chart_seriesA
Append a new to a named chart. value_field is the dataset field whose Sum becomes the Y expression (=Sum(Fields!<value_field>.Value)). series_type defaults to Column; combine series of different types in one chart for combo charts (e.g. Bar + Line). series_subtype defaults to Plain. Refuses if series_name already exists.
Inputs: path (required), chart_name (required), series_name (required), value_field (required), +2 more.
add_column_groupA
Add a column group that wraps the current top-level column hierarchy. Inserts a matching column at body column 0 (default 1in width) and a header cell at column 0 of every existing row with the group expression in the topmost cell. Mirrors add_row_group on the column axis. parent_group nesting is reserved for a future commit and currently raises NotImplementedError.
Inputs: path (required), group_name (required), tablix_name (required), group_expression (required), +1 more.
add_dataset_fieldA
Append a data-bound to a dataset's block. Writes data_field (and optional rd:TypeNametype_name</rd:TypeName>). Distinct from add_calculated_field which writes for derived fields. Use after rewriting the DAX to declare a new column that came back from the query but isn't yet in . Refuses on duplicate field name.
Inputs: path (required), data_field (required), field_name (required), dataset_name (required), +1 more.
add_dataset_filterA
Append a to the named dataset's block. operator ∈ Equal / NotEqual / GreaterThan / LessThan / GreaterThanOrEqual / LessThanOrEqual / Like / In / Between / TopN / BottomN / TopPercent / BottomPercent. values must be non-empty (single-value filters use a one-element list). Returns the new filter's index for later removal. Optional field_format wraps the expression as Format(, fmt) to coerce typed fields for string-parameter comparison. Response includes warnings for field/parameter type mismatches detected via best-effort cross-check.
Inputs: path (required), values (required), operator (required), expression (required), +2 more.
add_data_sourceA
Create a new for a Power BI XMLA endpoint. workspace_url accepts a bare workspace name or a full powerbi:// URL. Generates a fresh rd:DataSourceID GUID. Refuses if a DataSource of the same name already exists. provider='sql' (default) emits the legacy DataProvider=SQL + powerbi:// ConnectString + rd:SecurityType shape; provider='pbidataset' emits the modern PBI Desktop shape — DataProvider=PBIDATASET, pbiazure:// ConnectString with ClaimsToken auth, plus rd:PowerBIWorkspaceName / rd:PowerBIDatasetName siblings, no rd:SecurityType.
Inputs: name (required), path (required), dataset_name (required), workspace_url (required), +2 more.
add_embedded_imageA
Read a real image file off disk, base64-encode it, and store it under . Reference it later with image_source='Embedded' + value=. Supported MIME types: image/bmp, image/gif, image/jpeg, image/png, image/x-png. The file's magic bytes are sniffed and must match mime_type — claiming PNG bytes as image/jpeg is rejected here rather than letting Report Builder fail at preview time.
Inputs: name (required), path (required), mime_type (required), image_path (required).
add_header_imageB
Add an Image to /. image_source is External (URL in value), Embedded (EmbeddedImage Name in value), or Database (=Fields!Photo.Value-style expression).
Inputs: top (required), left (required), name (required), path (required), +4 more.
add_header_textboxA
Add a Textbox to /. text accepts static strings or RDL expressions (=Parameters!DateFrom.Value). Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).
Inputs: top (required), left (required), name (required), path (required), +3 more.
add_lineA
Add a to /. RDL Line semantics: top/left is the start point; width/height is the offset (vector) to the end point — horizontal line uses height='0in', vertical uses width='0in'. Optional color, line_thickness ('1pt' default), line_style (Solid/Dashed/Dotted/Double/etc.). Returns {name, kind: 'Line'}.
Inputs: top (required), left (required), name (required), path (required), +5 more.
add_listA
Add a List (single-cell repeating Tablix) bound to a dataset. RDL has no distinct element — Report Builder's List is a Tablix with one column, one detail row, and a Rectangle inside the cell. Items placed in the rectangle repeat once per dataset row. The inner rectangle is named '_Rect' for subsequent lookup. Returns {name, kind: 'Tablix', dataset, rectangle}.
Inputs: top (required), left (required), name (required), path (required), +3 more.
add_parameterA
Create a new ReportParameter with a minimal valid declaration. Appends to (creating it if absent). Pair with set_parameter_available_values / set_parameter_default_values afterwards for value lists. Booleans are only emitted when an explicit value is supplied.
Inputs: name (required), path (required), type (required), hidden, +4 more.
add_query_parameterA
Add a binding to a dataset's query. Use to wire report parameters into DAX (e.g. =Parameters!DateFrom.Value).
PBIDATASET parameter naming rule: in DAX/, write @MyParam (with @). In , write MyParam (no @). SQL/MDX use @ in both places. This tool detects the dataset's provider and AUTO-STRIPS a leading @ from name for PBIDATASET datasets, returning {normalised: true, warning: ...}. Pass force_at_prefix=true to override (rare; needed for some RSCustomDaxFilter patterns).
Inputs: name (required), path (required), dataset_name (required), value_expression (required), +1 more.
add_rectangleA
Add a to /. With no contained_items the rectangle is empty (a visual frame). With contained_items=[name1, name2, ...], each named body item is MOVED into the rectangle's and its / recalculated so the on-screen position is preserved. Refuses on duplicate name or if any contained_item isn't in /. Returns {name, kind: 'Rectangle', moved}.
Inputs: top (required), left (required), name (required), path (required), +3 more.
add_row_groupA
Add a row group that wraps the entire current top-level row hierarchy. Inserts a matching group-header row at body row 0 with the group expression in the first cell. parent_group (nesting under an existing group) is reserved for a future commit and currently raises NotImplementedError.
Inputs: path (required), group_name (required), tablix_name (required), group_expression (required), +1 more.
add_static_columnA
Add a static (no-group) column to a tablix. Each cell holds literal text. cells is a list of strings, one per body row (top to bottom); shorter list = blank trailing cells, longer list errors. Cell textboxes are named column_name (row 0) and column_name_<row_index> (others). position is 0-indexed; default appends. width defaults to 1in.
Inputs: path (required), column_name (required), tablix_name (required), cells, +2 more.
add_static_rowA
Add a static (no-group) row to a tablix. Each cell holds literal text. cells is a list of strings, one per body column (left to right); shorter list = blank trailing cells, longer list errors. Cell textboxes are named row_name (col 0) and row_name_<col_index> (others) — unique report-wide so row_name must not clash with any existing textbox. position is 0-indexed; default appends. height defaults to 0.25in.
Inputs: path (required), row_name (required), tablix_name (required), cells, +2 more.
add_subtotal_columnA
Column-axis mirror of add_subtotal_row. Adds a static TablixMember inside the column-group's , a new in TablixBody, and a cell at the new column index in every body row. aggregates is a list of {row, expression} entries where row is the 0-based body row index; rows not listed get blank cells. position='after' (default — canonical Grand Total slot, appends to the right of the column group) or 'before' (prepends to the group's left edge). width defaults to '1in'. Group must have been added via add_column_group.
Inputs: path (required), aggregates (required), group_name (required), tablix_name (required), +2 more.
add_subtotal_rowA
Append a subtotal row to a row-axis group. aggregates is a list of {column, expression} entries; column matches against the Details row's textbox names (the same names add_tablix_column uses as column_name — NOT field names). expression is the aggregate (e.g. =Sum(Fields!X.Value)). Columns not listed get blank cells. position='footer' (default) appends; 'header' inserts at body row 1 (right after the group-header row). Group must have been added via add_row_group.
Inputs: path (required), aggregates (required), group_name (required), tablix_name (required), +1 more.
add_tablix_columnA
Append (or insert) a column into a tablix. column_name is the textbox name placed in the data row's new cell — must be unique report-wide. expression goes inside that textbox's TextRun (typically =Fields!X.Value). For a tablix with >= 2 rows the first row gets header_text (default = column_name) as a literal, middle rows get blank cells, and the last row gets expression. position is 0-indexed; default appends at end. width defaults to 1in. Inserts a matching top-level TablixMember in the column hierarchy at the same index.
Inputs: path (required), expression (required), column_name (required), tablix_name (required), +3 more.
add_tablix_filterA
Append a to a tablix. Operator must be one of the RDL 2016 enumeration (Equal, NotEqual, GreaterThan, In, Between, ...). Returns the new filter's index for follow-up calls. Optional field_format wraps the expression as Format(, fmt) to coerce typed fields for string-parameter comparison. The response includes warnings for cross-checked field/parameter type mismatches.
Inputs: path (required), values (required), operator (required), expression (required), +2 more.
apply_editsA
Atomic batch: open once → apply ops → lint → save once. Opens an internal transaction against path, dispatches each {tool, args} op through the JSON-RPC tools/call path with transaction_id injected, and commits at the end. On any op failure or lint-error at commit, rolls back — disk is byte-identical to its pre-call state. Compare with dry_run_edit (clones to tempfile, never touches the real file): use dry_run_edit to preview a plan, apply_edits to land it. Returns {applied: [{tool, ok, result|error}], verify, committed}.
Inputs: ops (required), path (required).
backup_reportA
Copy the report to .bak.. Original is untouched. Cheap explicit checkpoint to call before a destructive batch (remove_*, rename_parameter, etc.). Returns the backup path. Set PBIRB_MCP_AUTO_BACKUP=1 to opt into automatic backups before destructive ops (off by default).
Inputs: path (required).
cancel_editing_transactionA
Discard a transaction. The in-memory tree is dropped; the on-disk file is unchanged from when the transaction was started. Returns {transaction_id, path, discarded}.
Inputs: transaction_id (required).
commit_editing_transactionA
Lint the in-memory tree, save to disk once (atomic .tmp + rename), and deregister. Aborts (saved=False) if lint surfaces any severity='error' issue — the transaction stays OPEN so the caller can fix the offending state and re-commit. Returns {transaction_id, path, saved, verify}.
Inputs: transaction_id (required).
convert_to_matrixA
Convert a row-grouped + column-grouped tablix into a matrix by dropping the residual Details row group and its body row. Pre-conditions (all checked): the named row_group and column_group must already exist (call add_row_group + add_column_group first); a must still be present in the row hierarchy. Refuses on second call (already a matrix). Use this after the standard insert_tablix_from_template + add_row_group + add_column_group flow to make the leaf the row group instead of Details — without this, cells render at detail granularity. Pair with set_tablix_corner (v0.4 commit 18) to author the top-left label.
Inputs: path (required), row_group (required), tablix_name (required), column_group (required).
count_whereA
Emit =Sum(IIf(, 1, 0)) — the SSRS conditional-count idiom. condition is an RDL expression body (no leading '='). Returns a complete top-level expression suitable for set_textbox_value or any RDL sink.
Inputs: condition (required).
create_reportA
Emit a minimal valid RDL from scratch at path. Refuses if path exists (no clobbering). Default page_setup is US Letter portrait with 1in margins; pass any subset of {page_height, page_width, margin_top, margin_bottom, margin_left, margin_right, body_width, body_height} to override. datasource is a forward-compat hook — pass {name, workspace_url, dataset_name, provider, integrated_security} to wire a real PBI XMLA endpoint (v0.4 commit 14); omit for a placeholder DataSource1 + DataSet1 stub the caller fills in via subsequent tools. Validates structurally + against the bundled XSD before saving (atomic .tmp + rename). Returns {path, validated, size_bytes}.
Inputs: path (required), datasource, page_setup.
describe_reportA
Top-level inventory of an RDL: data sources, datasets, parameters, tablixes, charts, and page setup. Always the first call when planning edits. v0.4: tablixes returns rich shape hints [{name, rows, columns, has_groups, has_subtotals, has_spans}] (was bare strings — migrate with [t['name'] for t in tablixes]). charts (new in v0.4) is a top-level array of chart names.
Inputs: path (required).
dry_run_editA
Apply a list of {tool, args} ops to a tempfile clone of the report; return the unified diff and a verify (validate + lint) report. The original file is NEVER modified. The harness auto-injects path into each op's args, so callers don't supply it. On op failure, dispatch stops; partial diff + verify are still returned. Use this to preview risky multi-step edits before committing.
Inputs: ops (required), path (required).
duplicate_reportA
Clone an .rdl to a new path. When regenerate_ids=true (default), every rd:DataSourceID and any rd:ReportID is rewritten to a fresh uuid4() so Power BI Report Builder doesn't refuse to load the duplicate due to identity collision. Atomic-write convention from RDLDocument.save_as. Refuses if dst_path already exists. Returns {src, dst, regenerated_ids: list[str]}.
Inputs: dst_path (required), src_path (required), regenerate_ids.
find_textbox_by_valueA
Find every Textbox whose text matches a Python regex pattern. Searches Body / PageHeader / PageFooter. A textbox with multiple matching runs surfaces once per match. Returns [{textbox, value, region}]. Useful for finding stale =Parameters!Old.Value references after rename_parameter, or any cross-cutting expression edit.
Inputs: path (required), pattern (required).
find_textboxes_by_styleA
Search for textboxes matching one or more style filters. Filters AND together (every supplied filter must match). Returns [{name, location, matched_fields}] where location is best-effort 'body' / 'header' / 'footer' / 'tablix:' / 'rectangle:'. Returns [] when no filters supplied. Pair with set_textbox_style_bulk for discovery+apply patterns (e.g. 'recolor every red textbox').
Inputs: path (required), color, format, font_size, +15 more.
get_chartA
Return effective state of a named Chart: position, size, dataset, palette, series list (name/type/subtype/value expression/color), category groups (name/expression/label), axes (category and value), legend, title, Style, Visibility. Symmetric with get_textbox / get_image / get_rectangle.
Inputs: name (required), path (required).
get_datasetB
Single-DataSet read-back (parity with get_textbox / get_image / get_rectangle / get_chart / get_data_source). Returns dataset name, data_source, command_text, fields (with both data_field and value), query_parameters, filters, and designer_state_present.
Inputs: name (required), path (required).
get_datasetsB
Full DAX command text, fields, query parameters, and dataset-level filters for every DataSet in the report.
Inputs: path (required).
get_data_sourceA
Single-DataSource read-back (parity with get_textbox / get_image / get_rectangle / get_chart). Returns the same shape as one entry of list_data_sources.
Inputs: name (required), path (required).
get_embedded_image_dataA
Read an embedded image's base64 for porting it to another report without re-reading from disk. Returns {name, mime_type, base64, byte_size}. base64 is the raw text of the ImageData element; byte_size is the decoded size for sanity-checking. Refuses with ElementNotFoundError if the named entry isn't in .
Inputs: name (required), path (required).
get_expression_referenceA
Return a static cheat-sheet of common RDL expression patterns: globals, parameters, fields, aggregates, conditionals, strings, dates. Each entry is {name, syntax, example, description}. Call this when authoring a textbox value or filter expression instead of guessing — and note the explicit encoding hint for the & concat operator.
Inputs: no named parameters.
get_imageB
Return effective state of a named Image: position, size, Source (External / Embedded / Database), Value, Sizing (AutoSize / Fit / FitProportional / Clip), MIMEType, Style, Visibility.
Inputs: name (required), path (required).
get_parametersC
Report parameter declarations: name, data type, prompt, flags.
Inputs: path (required).
get_rectangleB
Return effective state of a named Rectangle: position, size, names of contained ReportItems, Style, Visibility.
Inputs: name (required), path (required).
get_tablixesA
Tablix layout with stable IDs: columns, row/column groups, sort expressions, filters, visibility. Required input for any tablix edit.
Inputs: path (required).
get_textboxA
Return effective state of a named Textbox: position, size, Visibility, CanGrow, CanShrink, plus a nested style dict that mirrors set_textbox_style's routing — {box: {BackgroundColor, VerticalAlign, padding, ...}, border: {Style, Color, Width}, paragraph: {TextAlign}, run: {FontFamily, FontSize, FontWeight, Color, Format, ...}}. Empty branches are dropped. runs[] entries each carry their own per-run style. Searches the entire report; tablix-cell textboxes have None for top/left/width/height. Top-level positioned items with a missing or coerce to '0in' (RDL default).
Inputs: name (required), path (required).
iif_formatA
Emit =IIf(, <true_value>, <false_value>). All three args are expression bodies (no leading '='); string literals must already be quoted, e.g. true_value='"Yes"'.
Inputs: condition (required), true_value (required), false_value (required).
insert_chart_from_templateA
Build and append a basic Column chart to /. Single category axis grouped by category_field; single Y series Sum(Fields!<value_field>.Value). dataset_name must already exist. Change post-insert (e.g. to Bar / Line / Pie) by editing the chart directly.
Inputs: top (required), left (required), name (required), path (required), +5 more.
insert_tablix_from_templateA
Build and append a basic Tablix to /. One column per name in columns; header row gets the column name as a static label, detail row binds to =Fields!.Value. dataset_name must already exist. width is the tablix outer width — each column defaults to 1in regardless, so for a 3-column tablix the columns sum to 3in even if you pass width=10cm. Resize columns afterwards via direct edits or future column-width tools.
Inputs: top (required), left (required), name (required), path (required), +4 more.
lint_reportA
Run static-analysis lint rules against an .rdl. Sixteen rules cover the v0.2/v0.3 sweep bug classes (multi-value-eq, missing-field-reference, dangling-embedded-image, pbidataset-at-prefix, parameter-layout-out-of-sync, double-encoded-entities, stale-designer-state, tablix-span-misplaced, dataset-fields-out-of-sync, etc.). Returns {issues, rules_run} with each issue {severity, rule, location, message, suggestion?}. Optional rules selects a subset by name.
Inputs: path (required), rules.
list_body_itemsA
List every named ReportItem at the top level of . Returns name, type (Tablix / Textbox / Image / Rectangle / Subreport / Chart / etc.), top, left, width, height. Use before set_body_item_position / set_body_item_size when you don't already know what's in the body.
Inputs: path (required).
list_dataset_filtersA
List dataset-level filters in document order. Returns [{expression, operator, values}]; index in the list is the stable handle for remove_dataset_filter. DataSet filters apply to every consumer of the dataset (every Tablix / Chart bound to it); use list_tablix_filters for per-tablix filtering.
Inputs: path (required), dataset_name (required).
list_data_sourcesA
Return a rich list of every in the report — name, data_provider, connect_string, integrated_security, shared_reference, security_type, data_source_id. describe_report.data_sources returns names only; this tool is the authoring-friendly read.
Inputs: path (required).
list_embedded_imagesB
List embedded images in the report by name and MIME type. Returns an empty list when is absent.
Inputs: path (required).
list_header_itemsC
Same shape as list_body_items but for .
Inputs: path (required).
list_tablix_filtersA
List all filters on a named tablix in document order. Returns expression, operator, and values per filter; index in the list is the stable handle for remove_tablix_filter.
Inputs: path (required), tablix_name (required).
raw_xml_replaceA
Replace the single element matched by xpath with new content. content is parsed with RDL as the default namespace and 'rd:' bound, so bare names like x work without explicit xmlns. Refuses on zero matches, multiple matches, or if the xpath targets the root. Saves atomically. Returns {xpath, kind, changed}.
Inputs: path (required), xpath (required), content (required).
raw_xml_viewA
Read-only XPath query against the report. Returns matched elements as serialised XML strings. XPath context is (the root); 'r:' is bound to the RDL namespace, 'rd:' to the rd namespace. Examples: "r:DataSources/r:DataSource[@Name='X']" / ".//r:Textbox[@Name='X']/r:Style". Returns [] when nothing matches; raises on malformed xpath.
Inputs: path (required), xpath (required).
refresh_dataset_fieldsA
Sync a dataset's block against the shape detected in its DAX . Eliminates the manual 'open Report Builder → right-click → Refresh Fields' step after a query rewrite. Recognises SELECTCOLUMNS aliases and Table[Col] tokens (SUMMARIZECOLUMNS / ad-hoc). Adds missing fields; lists orphans without auto-removing (caller decides what to drop). Returns {added, orphans, unchanged, warnings}. Cheap regex-based detection — bare EVALUATE 'Table' returns a warning.
Inputs: path (required), dataset_name (required).
remove_body_itemA
Remove a named item (Textbox, Image, or Tablix) from /. Destructive but explicit — raises if the name doesn't match anything.
Inputs: name (required), path (required).
remove_calculated_fieldA
Remove a calculated by name. Refuses if the field is data-bound (carries instead of ) — those reflect the source query's columns. Drop a data-bound field via remove_dataset_field, or rewrite the dataset query via update_dataset_query.
Inputs: path (required), field_name (required), dataset_name (required).
remove_chart_seriesA
Remove a named from a chart. Refuses to remove the last remaining series (use remove_body_item to drop the whole chart instead). Returns {chart, removed, remaining}.
Inputs: path (required), chart_name (required), series_name (required).
remove_column_groupA
Inverse of add_column_group: unwraps a column-axis group's children back to the top of the column hierarchy and removes the matching body column at position 0 (along with each row's first cell). Errors if group_name only exists on the row axis.
Inputs: path (required), group_name (required), tablix_name (required).
remove_dataset_fieldA
Remove a data-bound by name (one with ). Symmetric counterpart to remove_calculated_field. Refuses on calculated fields (use remove_calculated_field instead) and on still-referenced fields (any expression containing Fields!.Value / .IsMissing / .Count). Pass force=True to delete anyway. Closes the cookbook flow: refresh_dataset_fields lists orphans, remove_dataset_field drops them. Returns {dataset, removed, kind: 'DataBoundField'}.
Inputs: path (required), field_name (required), dataset_name (required), force.
remove_dataset_filterA
Remove a dataset-level filter by its 0-based document-order index. Cleans up the empty block when removing the last entry.
Inputs: path (required), dataset_name (required), filter_index (required).
remove_data_sourceA
Remove a named . Refuses by default if any DataSet/Query/DataSourceName or DataSource/DataSourceReference still references it; the error lists the offending locators. Pass force=True to remove anyway.
Inputs: name (required), path (required), force.
remove_embedded_imageA
Remove a named embedded image. Refuses (lists offending Image elements) when any =name> still references it; pass force=True to remove anyway and accept the dangling references. Drops the empty block when removing the last entry.
Inputs: name (required), path (required), force.
remove_header_itemB
Remove a named Textbox or Image from /. Empties the ReportItems block when the last item leaves.
Inputs: name (required), path (required).
remove_parameterA
Remove a ReportParameter by name. Refuses (lists offending locators) if the parameter is still referenced anywhere in the report by Parameters!.Value or .Label. Pass force=True to remove anyway.
Inputs: name (required), path (required), force.
remove_query_parameterB
Remove a query parameter from a dataset. Cleans up the empty block when removing the last one.
Inputs: name (required), path (required), dataset_name (required).
remove_row_groupA
Inverse of add_row_group: unwraps a group's children back to its parent hierarchy and removes the matching header row at body row 0. Refuses to remove the conventional Details group.
Inputs: path (required), group_name (required), tablix_name (required).
remove_tablix_columnA
Remove the tablix column whose data-row cell holds a textbox named column_name. Drops the matching TablixColumn, removes the top-level TablixMember at that column index (only if it's a leaf, never a column group wrapper), and removes the cell at that index from every TablixRow. Errors if no row contains a textbox with the given name.
Inputs: path (required), column_name (required), tablix_name (required).
remove_tablix_filterA
Remove a filter by index. Filters are anonymous in RDL, so use list_tablix_filters first to find the right index. Removing the last filter also drops the empty block.
Inputs: path (required), tablix_name (required), filter_index (required).
rename_data_sourceA
Rename a and rewrite every reference: DataSet/Query/DataSourceName entries AND any DataSource/DataSourceReference shared-source links. Atomic: stages all matches before committing. Errors if new_name already exists or equals old_name.
Inputs: path (required), new_name (required), old_name (required).
rename_parameterA
Rename a ReportParameter and rewrite every textual occurrence of Parameters!<old_name>.Value / .Label across the entire report. Case-sensitive. Atomic: collects all matches first, then commits. Errors if new_name already exists or equals old_name.
Inputs: path (required), new_name (required), old_name (required).
reorder_parametersA
Reorder children to match the supplied names list. names MUST be a permutation of every existing parameter — no missing, no duplicates, no unknown names. When a exists, its CellDefinition entries are reordered in lockstep so the parameter pane shows fields in the new declaration order. RowIndex / ColumnIndex are not recomputed (RB's layout grid is independent of declaration order). Returns {order, kind, changed: bool}; same order → no save.
Inputs: path (required), names (required).
restore_from_backupA
Restore a backup file over its original target. target_path defaults to the path implied by the backup's .bak. filename; pass target_path explicitly when the backup name doesn't match that shape. Refuses if target mtime is newer than backup (staleness guard) — pass force=True to override. Returns {source, restored_to, bytes_restored}.
Inputs: backup_path (required), force, target_path.
set_alternating_row_colorA
Zebra-stripe a tablix's detail row by writing BackgroundColor=IIf(RowNumber(Nothing) Mod 2, color_a, color_b) on every detail cell's Textbox. Walks the row hierarchy to find the Details leaf — works after add_row_group nests the structure deeper. Replaces any existing BackgroundColor.
Inputs: path (required), color_a (required), color_b (required), tablix_name (required).
set_body_item_positionA
Move an existing named ReportItem inside to (top, left). Preserves all other properties (size, style, group structure). top and left are passed through verbatim — RDL accepts any size unit (2cm, 0.75in, 108pt). Errors if no body item by that name.
Inputs: top (required), left (required), name (required), path (required).
set_body_item_sizeA
Resize an existing named ReportItem inside . At least one of width / height must be supplied; missing fields are left untouched. Same RDL size-string convention as the position tools.
Inputs: name (required), path (required), width, height.
set_body_sizeA
Set the body's rendering region inside the page. / and / (the sibling of ) — both are RDL size strings (e.g. '14in', '9in', '297mm'). Either or both kwargs required. Distinct from set_page_setup (which sets the paper chrome //) and set_body_item_size (size of items inside the body). Use this when a wide tablix or chart needs the body region expanded — without it the right edge is clipped at preview time. Idempotent: same value → empty changed. Returns {kind: 'Body', changed: list[str]}.
Inputs: path (required), width, height.
set_cell_spanA
Set and/or on a tablix cell. The cell is addressed by (row_index, column_name) where column_name is the textbox name inside the cell. At least one of row_span / col_span must be supplied; both must be >= 1. Pass 1 to explicitly reset a span. Replaces existing values if present.
Inputs: path (required), row_index (required), column_name (required), tablix_name (required), +2 more.
set_chart_axisA
Configure a chart axis: title (Caption), format (numeric/date format string in /), min/max range, log_scale, interval, visible. axis ∈ {Category, Value}; axis_name defaults to 'Primary' (the only axis the template emits — pass a real name for secondary axes). All field args are optional; pass '' to clear an element. Returns {chart, axis, axis_name, kind, changed: list[str]} with the affected sub-element names.
Inputs: axis (required), path (required), chart_name (required), max, +7 more.
set_chart_data_labelsA
Configure on one or all series in a chart. When series_name is None, the change applies to every series; otherwise only the named series. visible writes true|false; visible_expression writes the same element with a VB.NET =IIf(...) expression (mutually exclusive with visible). format writes /; pass '' to clear. v0.4: position ∈ Auto/Top/TopLeft/TopCenter/TopRight/Left/Center/Right/BottomLeft/BottomCenter/BottomRight/Bottom/Outside; use_value_as_label ∈ true/false; font_weight + color write to / and / (pass '' to clear). Returns {chart, series, kind, changed}.
Inputs: path (required), chart_name (required), color, format, +6 more.
set_chart_legendA
Configure a chart legend: position (TopLeft / TopCenter / TopRight / LeftTop / LeftCenter / LeftBottom / RightTop / RightCenter / RightBottom / BottomLeft / BottomCenter / BottomRight) and visible (writes true|false). legend_name defaults to 'Default' (the only one the template emits). Returns {chart, legend, kind, changed: list[str]}; no-op short-circuit when nothing supplied.
Inputs: path (required), chart_name (required), visible, position, +1 more.
set_chart_paletteA
Set on a chart. palette ∈ Default / EarthTones / Excel / GrayScale / Light / Pastel / SemiTransparent / Berry / Chocolate / Fire / SeaGreen / BrightPastel. Pass '' to clear (RB falls back to its built-in default palette). Returns {chart, kind, changed: bool}.
Inputs: path (required), palette (required), chart_name (required).
set_chart_series_actionA
Set / to a Hyperlink (URL), Drillthrough (another report + optional parameters), or BookmarkLink. Same kwarg surface as set_textbox_action / set_image_action; the chart series is addressed by (chart_name, series_name). Schema-aware insertion respects ChartSeries child order. Idempotent on structural equality of the inner block.
Inputs: path (required), chart_name (required), action_type (required), series_name (required), +2 more.
set_chart_series_groupingA
Promote a chart's static ChartMember to a dynamic-fanout series. Writes /////. At render time, one rendered series is produced per distinct value of the group expression — the '13 violation types unknown at design time' fan-out. group_field='Type' is a shorthand for =Fields!Type.Value; group_expression accepts any VB.NET. Mutually exclusive. replace=False (default) refuses if the ChartMember already has a ; pass replace=True to overwrite. Operates on the FIRST ChartMember in the hierarchy (v0.4 commit 21 scope; multi-member chains aren't reachable from any v0.4 tool). Returns {chart, series, kind: 'ChartGroup', group_name, expression, changed}.
Inputs: path (required), chart_name (required), series_name (required), replace, +2 more.
set_chart_series_typeA
Update and optionally on a named ChartSeries. Combo charts work by setting different types per series in the same chart (e.g. one Bar series and one Line series). v0.4: series_subtype defaults to null/None — omit to PRESERVE the existing subtype. Pass 'Stacked' / 'PercentStacked' / 'Plain' / etc. to override. Pre-v0.4 always wrote 'Plain' by default, silently resetting stacked-bar charts on type-only edits. Returns {chart, series, kind, changed: list[str]} — empty when inputs match existing values.
Inputs: path (required), chart_name (required), series_name (required), series_type (required), +1 more.
set_chart_titleA
Update /. text can be literal text or an =expression. title_name defaults to 'Default' (the only title the template emits). Returns {chart, title, kind, changed: bool}.
Inputs: path (required), text (required), chart_name (required), title_name.
set_column_group_sortA
Replace a column-axis group's with a fresh list. Mirrors set_group_sort but refuses up front if group_name is on the row axis (use set_group_sort instead).
Inputs: path (required), group_name (required), tablix_name (required), sort_expressions (required).
set_column_group_visibilityA
Set on a column-axis group's TablixMember. Accepts a Hidden expression and an optional ToggleItem (textbox name that toggles expand/collapse). Mirrors set_group_visibility but refuses up front if group_name is on the row axis.
Inputs: path (required), group_name (required), tablix_name (required), visibility_expression (required), +1 more.
set_column_widthA
Set on a tablix's body column. column accepts a 0-based integer index OR a textbox name living in any cell of that column (mirrors how set_cell_span / add_subtotal_row address columns). width is an RDL size ('1.5in', '4cm', '80pt'). Idempotent: same width → {changed: false}, no save.
Inputs: path (required), width (required), column (required), tablix_name (required).
set_conditional_row_colorA
Color every cell of a tablix's detail row based on the value of one of its fields. Builds a Switch(...) expression mapping field values to colors and writes it as BackgroundColor on every detail cell. value_expression is the field reference (e.g. 'Fields!Status.Value' — a leading '=' is accepted). color_map is an ordered dict of value->color (e.g. {"Red":"#FF0000","Yellow":"#FFFF00"}); first match wins. Unmatched values fall back to default_color (default 'Transparent'). When case_sensitive is False (default), wraps the field reference in UCase() and uppercases the keys for case-insensitive matching. Walks the row hierarchy to find the Details leaf — works after add_row_group nests the structure. Replaces any existing BackgroundColor.
Inputs: path (required), color_map (required), tablix_name (required), value_expression (required), +2 more.
set_datasource_connectionA
Repoint a DataSource at a Power BI XMLA endpoint. workspace_url accepts a bare workspace name or a full powerbi:// URL; DataProvider is set to SQL (the AS provider id in RDL).
Inputs: name (required), path (required), dataset_name (required), workspace_url (required), +1 more.
set_detail_row_visibilityB
Set on the tablix's Details group, optionally with a ToggleItem textbox name. Use to hide detail rows by expression without restructuring the row hierarchy.
Inputs: path (required), expression (required), tablix_name (required), toggle_textbox.
set_document_map_labelA
Set on any named ReportItem (Textbox / Image / Rectangle / Chart / Tablix / etc.). Surfaces in the rendered report's navigable document-map / table-of-contents pane. Pass '' to clear. Idempotent. Returns {element, kind, changed: bool}.
Inputs: path (required), element_name (required), label_or_expression (required).
set_element_visibilityA
Set on any named ReportItem (Tablix, Textbox, Image, Rectangle, Subreport, Chart). For group-level visibility use set_group_visibility; for detail-row use set_detail_row_visibility. toggle_textbox optionally points at a textbox name that toggles expand/collapse.
Inputs: path (required), element_name (required), hidden_expression (required), toggle_textbox.
set_group_page_breakA
Set on a tablix group's page-break rule. location ∈ {None, Start, End, StartAndEnd, Between}. Passing 'None' removes the element (the canonical 'no break' shape). Idempotent. Returns {tablix, group, kind: 'Group', location, changed}.
Inputs: path (required), location (required), group_name (required), tablix_name (required).
set_group_sortC
Replace a group's with a fresh list. Each entry is an RDL expression, e.g. =Fields!Region.Value.
Inputs: path (required), group_name (required), tablix_name (required), sort_expressions (required).
set_group_visibilityB
Set on a group's TablixMember. Accepts a Hidden expression and an optional ToggleItem (a textbox name that toggles the group expand/collapse).
Inputs: path (required), group_name (required), tablix_name (required), visibility_expression (required), +1 more.
set_header_item_positionA
Move an existing named ReportItem inside to (top, left). Errors if there is no (call set_page_header first) or no item by that name.
Inputs: top (required), left (required), name (required), path (required).
set_header_item_sizeA
Resize a named item inside . Mirrors set_body_item_size — at least one of width / height; missing fields untouched; idempotent ({changed: false} when nothing differs). Closes the v0.2 parity gap where only the body variant existed.
Inputs: name (required), path (required), width, height.
set_image_actionA
Same shape as set_textbox_action but operates on a named . action_type ∈ Hyperlink / Drillthrough / BookmarkLink. Returns {image, kind, action_type, changed}.
Inputs: path (required), image_name (required), action_type (required), target_expression (required), +1 more.
set_image_sizingA
Set / on a named Image. sizing ∈ AutoSize / Fit / FitProportional / Clip. AutoSize renders at native size (box grows to fit); Fit stretches to fill (ignores aspect ratio); FitProportional preserves aspect ratio; Clip renders at native size, clipped to the box. Idempotent: same value → {changed: false}, no save.
Inputs: path (required), sizing (required), image_name (required).
set_image_sourceA
Repoint an existing at a different embedded image entry without delete-and-readd. Sets Source=Embedded and rewrites to embedded_name. Refuses with a clear error if embedded_name isn't in — leaving a dangling reference would render as a broken image. Add the image first via add_embedded_image. Idempotent: same (Source, Value) pair → {changed: false}, no save. Returns {name, kind, changed: bool}.
Inputs: path (required), image_name (required), embedded_name (required).
set_keep_togetherA
Set on a named Tablix / Rectangle / Chart / Textbox / Map / Gauge. Tells the renderer 'don't split this across pages if you can help it'. Best-effort — items larger than a page are still split. keep=False removes the element. Refuses for Image / Line / Subreport and other kinds where the RDL XSD doesn't allow it.
Inputs: keep (required), name (required), path (required).
set_keep_with_groupA
Set / on the member that wraps the named group. value ∈ {None, Before, After}. Typical use: a column-header row's member with 'After' to glue it to the data rows that follow. value='None' removes the element.
Inputs: path (required), value (required), group_name (required), tablix_name (required).
set_page_headerB
Create or update : height plus PrintOnFirstPage / PrintOnLastPage flags. All fields optional — only what's passed gets written.
Inputs: path (required), height, print_on_last_page, print_on_first_page.
set_page_orientationA
Set page orientation by swapping PageHeight and PageWidth when the current orientation doesn't match the requested one. Idempotent. Accepts 'Portrait' or 'Landscape'.
Inputs: path (required), orientation (required).
set_page_setupB
Update dimensions, margins, and column count on the first ReportSection. All fields are optional — only what's passed gets written. columns=1 strips the element.
Inputs: path (required), columns, margin_top, page_width, +4 more.
set_parameter_available_valuesA
Set or clear on a report parameter. source='static' with a non-empty static_values writes a list of entries (each entry can be a string or {value, label} dict). source='static' with static_values=[] or omitted CLEARS the element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a to a lookup dataset. Replaces any existing block.
Inputs: name (required), path (required), source (required), query_dataset, +3 more.
set_parameter_default_valuesA
Set or clear on a report parameter. source='static' with a non-empty static_values writes a list of expressions. source='static' with static_values=[] or omitted CLEARS the element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a with ValueField only (no LabelField — defaults are values, not display strings). Replaces any existing block.
Inputs: name (required), path (required), source (required), query_dataset, +2 more.
set_parameter_layoutA
Author / explicitly. Writes + ; rewrites so each name in parameter_order lands at (row=index // columns, col=index % columns). Strict permutation check (every existing parameter exactly once). rows*columns must be ≥ parameter count. Auto-creates the layout block when absent. Idempotent: same grid + order → no save. Complements reorder_parameters (declaration order) and sync_parameter_layout (gap-filling). Returns {rows, columns, order, kind, changed}.
Inputs: path (required), rows (required), columns (required), parameter_order (required).
set_parameter_promptA
Write the text on a ReportParameter. Empty string clears the element entirely; pass a single space ' ' for blank-but-present.
Inputs: name (required), path (required), prompt (required).
set_parameter_typeA
Set on a ReportParameter. type ∈ {Boolean, DateTime, Integer, Float, String}. Rejects with ValueError if any existing literal default value would be incompatible with the new type — fix defaults first via set_parameter_default_values, then retry.
Inputs: name (required), path (required), type (required).
set_repeat_on_new_pageB
Set / on the member that wraps the named group. Most common use: repeat a group header row at the top of every page the group spans. Setting repeat=False removes the element (False is default). Returns {tablix, group, kind: 'TablixMember', repeat, changed}.
Inputs: path (required), repeat (required), group_name (required), tablix_name (required).
set_row_heightA
Set the Height of the Nth body row (0-indexed) in a tablix. Accepts any RDL size string ('0.25in', '1cm', '12pt').
Inputs: path (required), height (required), row_index (required), tablix_name (required).
set_series_colorA
Write into a named series's block, overriding the chart palette for just that series. color accepts a named color ('Red'), a hex string ('#FF0000'), or an =expression. Pass '' to clear (series falls back to the palette). Returns {chart, series, kind, changed: bool}.
Inputs: path (required), color (required), chart_name (required), series_name (required).
set_tablix_cornerA
Write the block — the top-left cell of a matrix-shaped tablix that holds the row-axis caption (e.g. 'Type'). Pass text for a literal value OR expression for a VB.NET '=...' formula. Mutually exclusive. Textbox name is deterministic: '<tablix_name>_Corner'. Refuses if the tablix has no named column group (the corner is only meaningful in a matrix). Replaces any existing TablixCorner block. Returns {tablix, name, kind: 'TablixCorner', changed}.
Inputs: path (required), tablix_name (required), text, expression.
set_tablix_sizeA
Resize a tablix by writing and / or directly. Each arg independently optional. Use after adding header / footer rows that change the body's natural height — v0.2's positioning tools only cover top/left, not size. Both values are RDL size strings. Returns {tablix, kind, changed: list[str]} — empty list when inputs match existing.
Inputs: name (required), path (required), width, height.
set_textbox_actionA
Set / to a Hyperlink (URL), Drillthrough (another report + optional parameters), or BookmarkLink (jump within document). target_expression accepts literal text or =expression. drillthrough_parameters is a list of {name, value} dicts wired into /. Idempotent: same action_type + target + parameters → {changed: false}, no save.
Inputs: path (required), action_type (required), textbox_name (required), target_expression (required), +1 more.
set_textbox_runsA
Replace a textbox's content with multiple children for mixed styling within one display — e.g. 'Asset(s): value' with a bold prefix + regular value in a single textbox. Each run is a dict with required 'text' and optional font_family / font_size / font_weight / font_style / color / format / text_decoration. Replaces the entire subtree (single-paragraph in v0.3; multi-paragraph deferred). Round-trip contract: get_textbox.runs[] returns the same shape this tool writes. Idempotent — identical input is a no-op short-circuit. Returns {textbox, kind, runs, changed}. Pass raw text in each run's text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator).
Inputs: path (required), runs (required), textbox_name (required).
set_textbox_styleA
Set styling on a named Textbox. Properties route to the right nested Style node automatically: background_color, border_*, vertical_align, padding_*, writing_mode go on Textbox/Style; text_align on Paragraph/Style; font_*, color, format on TextRun/Style; can_grow / can_shrink go DIRECTLY on Textbox (not inside Style). All fields optional — only what's passed gets written. Cell-level styling: every tablix cell is a Textbox with a unique name, so use this tool with the cell's textbox name (e.g. 'HeaderAmount').
Inputs: path (required), textbox_name (required), color, format, +16 more.
set_textbox_style_bulkA
Apply the same style kwargs to every named textbox in one call. Same kwarg surface as set_textbox_style. Missing names land in skipped rather than raising. Returns {textboxes, skipped, changed} where changed is the union of sub-paths affected across all textboxes. Pair with find_textboxes_by_style to discover names by current style.
Inputs: path (required), textbox_names (required), color, format, +16 more.
set_textbox_tooltipA
Set /. Literal text or =expression. Pass '' to clear. Idempotent. Returns {textbox, kind, changed: bool}.
Inputs: path (required), textbox_name (required), text_or_expression (required).
set_textbox_valueA
Replace the text content of a single-run textbox. value can be raw text or an =expression. Use this for the everyday 'change the textbox content' case (swap a literal label, update a stale parameter reference, replace a broken aggregate). Refuses with a redirect to set_textbox_runs when the textbox has multiple text runs (multi-run content needs the rich-text editor). Idempotent: identical value → {changed: false} no-op. Returns {textbox, kind, changed}. Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).
Inputs: path (required), value (required), textbox_name (required).
start_editing_transactionA
Open the report and start an editing transaction. Returns {transaction_id, path, expires_at}. Pass transaction_id to subsequent edit tools to mutate the live in-memory tree WITHOUT touching disk between calls — eliminates the per-edit parse+serialize round-trip. The transaction times out after PBIRB_MCP_TRANSACTION_TIMEOUT_S seconds (default 600); call commit_editing_transaction to flush or cancel_editing_transaction to discard. Refuses if an active transaction already owns this path.
Inputs: path (required).
style_tablix_rowA
Apply the same style kwargs to every cell in a tablix row in ONE call. Replaces the 12-individual-set_textbox_style-calls-per-row pattern. row accepts: integer (0-based body row index), 'header' (first leaf with KeepWithGroup=After — the column header row), 'details' (the Details leaf row), 'header' (header row of a named row group), 'footer' (footer row when present, e.g. after add_subtotal_row). Same style kwargs as set_textbox_style (font*, color, background_color, border, padding_, writing_mode, can_grow, can_shrink, etc.). Delegates writes to set_textbox_style_bulk. Returns {tablix, row, row_index, kind, cells, changed, skipped}.
Inputs: row (required), path (required), tablix_name (required), color, +17 more.
sum_whereA
Emit =Sum(IIf(, <field_expression>, 0)) — the SSRS conditional-sum idiom. Both args are expression bodies (no leading '=').
Inputs: condition (required), field_expression (required).
sync_parameter_layoutA
Bring // into sync with . Drops cells whose ParameterName no longer exists; appends cells for parameters that have no entry, placed at the next free (row, col) slot. add_parameter / remove_parameter / rename_parameter call this internally; the standalone tool is for repairing legacy reports authored before v0.3.0 where the layout drifted. No-op when the report has no . Returns {added, removed}.
Inputs: path (required).
update_dataset_queryA
Replace the DAX command text of a named dataset. The full DAX expression is accepted verbatim; empty bodies are rejected. Optional alias_strategy='preserve_field_names' positionally rewrites cells to the new DAX columns while keeping existing identifiers — so Fields!X.Value references in expressions keep resolving.
Inputs: path (required), dax_body (required), dataset_name (required), alias_strategy.
update_parameter_advancedA
Toggle the four boolean flags on a report parameter: multi_value, hidden, allow_null (writes ), allow_blank. Each is independently optional. With no flags passed it's a no-op. Cascading parameters are NOT a flag — use set_parameter_available_values(source='query') + add_query_parameter on the lookup dataset to wire a dependency on another parameter.
Inputs: name (required), path (required), hidden, allow_null, +2 more.
update_query_parameterB
Change the value expression of an existing query parameter. Same PBIDATASET @-prefix normalisation as add_query_parameter applies on lookup; legacy Name='@X' parameters that already exist on disk are addressable via either @X or X.
Inputs: name (required), path (required), dataset_name (required), value_expression (required), +1 more.
validate_reportA
Run schema/structural validation against an .rdl. Returns {valid, errors, xsd_used}. Structural checks always run (root element + required top-level sections). The Microsoft RDL 2016/01 XSD is bundled by default since v0.3.1 — when it's loaded, xsd_used is True and the schema-conformance bug class Power BI Report Builder rejects on load gets caught here. If the bundled XSD is missing (source-build without package-data) a {severity:warning, rule:'xsd-not-bundled'} issue surfaces instead of silent skip. Each issue is {severity, rule, location, message, suggestion?}; valid is True iff no severity='error' issue.
Inputs: path (required).
verify_reportA
One-shot static check: union of validate_report and lint_report. Returns {valid, issues, xsd_used} where valid is True iff no issue has severity='error'. Warnings (including 'xsd-not-bundled' when the schema file is missing) don't invalidate the report. Use this as the single 'is the report OK?' tool, or set PBIRB_MCP_AUTO_VERIFY=1 to have it run after every mutating call.
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 143 tools
Every tool has a clearly distinct purpose with detailed descriptions, ranging from adding, removing, setting, getting, listing, and updating various report elements. There is no ambiguity; each tool targets a specific report component or operation.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_body_image, set_textbox_value, list_data_sources). No mixing of conventions or styles.
143 tools is an extreme mismatch for typical MCP servers, even considering the complex domain of RDL report editing. The count far exceeds the '25+' threshold for 'too many', making it difficult for agents to navigate and select appropriately.
The tool set covers the full lifecycle of RDL report creation and manipulation: CRUD for all major elements (data sources, datasets, parameters, tablixes, charts, images, etc.), plus validation, linting, backup, and editing transactions. No obvious gaps.
Maintenance
Related MCP Connectors
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- AlicenseBqualityDmaintenanceBuild Power BI reports with natural language through an MCP server that connects AI assistants to Power BI's PBIR file format for creating pages, visuals, themes, and filters locally.25721MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Microsoft Power BI and Fabric, enabling Claude to discover workspaces, semantic models, generate and execute DAX queries, and retrieve report metadata via device-code authentication.14 npm1MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for creating, editing, and evaluating Power BI (.pbix/.pbit) files without Power BI Desktop. Supports 101 tools including report creation, data sources, DAX measures, and file manipulation.1,233 PyPI25MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for managing Microsoft Fabric Reports with lifecycle management, filtering, and content manipulation.8-