BI Portal Report Builder MCP Server
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., "@BI Portal Report Builder MCP Server list available datasets for reporting"
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.
BI Portal — Report Builder MCP Server
An MCP server exposing the BI Portal's self-service Report Builder to MCP clients (Claude Desktop, Claude Code, or any other MCP-speaking agent): list datasets, run ad-hoc queries, create/edit/submit draft reports, and view saved dashboards.
Why this is its own repo, not part of backend/
It's a thin HTTP client of the backend's REST API — no backend Python imports, no
direct Postgres access. Everything it does goes through the exact same
/api/explore/*, /api/reports/*, and /api/dashboards/* endpoints the React UI
uses, so every RBAC check the backend already enforces applies automatically; this
server can't become a second, independently-drifting authorization path. Being a
separate repo means it deploys, versions, and can break independently of the backend
and UI — see the root docs/architecture.md for the fuller
rationale on why this was cut out as its own service while Report Builder's actual
query logic stayed in the backend.
Related MCP server: powerbi-mcp-proxy
Two identity modes
Every tool call is attributed to whichever Bearer token this process is configured with — the server itself doesn't know or care which mode is active, only the backend does.
delegated(default) — acts as a real logged-in human, inheriting exactly their roles. Mint a token from the backend while your portal session is live:curl -X POST http://localhost:8000/auth/token \ -H "Content-Type: application/json" \ -b "session=<your browser's session cookie>" \ -d '{"label": "my MCP client"}'The response's
tokenfield (pat_...) is shown once — copy it intoBI_PORTAL_TOKEN.fixed— acts as a standing service identity (e.g. aFinanceReportGen-scoped account) independent of who's driving the agent. An Admin mints one:curl -X POST http://localhost:8000/api/admin/service-identities \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <an Admin's pat_ token>" \ -d '{"name": "mcp-reportsgen", "groups": ["FinanceReportGen"]}'The response's
tokenfield (svc_...) is shown once — copy it intoBI_PORTAL_TOKEN.
Setup
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # fill in BI_PORTAL_BASE_URL / BI_PORTAL_AUTH_MODE / BI_PORTAL_TOKEN
pytest # runs against a mocked backend, no live server neededRun directly over stdio (what most desktop MCP clients expect):
python -m mcp_bi_portal.serverExample Claude Desktop / Claude Code MCP client config:
{
"mcpServers": {
"bi-portal-report-builder": {
"command": "/path/to/mcp-server/.venv/bin/python",
"args": ["-m", "mcp_bi_portal.server"],
"env": {
"BI_PORTAL_BASE_URL": "http://localhost:8000",
"BI_PORTAL_AUTH_MODE": "delegated",
"BI_PORTAL_TOKEN": "pat_..."
}
}
}
}Tools
Tool | Backend endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Review/approve is deliberately not exposed — the tool surface is scoped to
authoring, not the full REST API. (For a fixed ReportGen-style identity this is also
enforced server-side, not just by omission here: require_domain_review_access
rejects any identity that isn't in a domain's admin_group_name.)
Deployment
MCP servers for desktop/CLI clients are conventionally a local subprocess over stdio,
launched by the client itself — there's no standing network service by default, unlike
backend/ui. See deployment/README.md for the optional
streamable-http path and why the K8s manifests for this service are marked optional.
Available Tools
8 toolscreate_draft_reportA
Create a new draft report in the caller's personal workspace — visible only
to the caller until submitted. dashboard_kind is typically "report_builder"
(multiple independently-queried sections, each its own dataset/dimensions/
measures/filters/visualization) or "custom_query" (one query, one chart).
target_domain_key should match the domain of the report's primary dataset —
this is what the report gets submitted into for review. config_json holds
that dashboard_kind's own configuration; build it up by test-running each
section with run_explore_query first so the dimensions/measures/filters are
known to work and to have a sensible recommended visualization.
Inputs: title (required), config_json (required), dashboard_kind (required), target_domain_key (required).
get_reportB
Fetch a report's metadata: title, status, dashboard_kind, and its full config_json.
Inputs: report_id (required).
list_datasetsA
List every dataset the caller's identity can query. Each entry includes the
dataset key, label, owning domain, and its columns — each column's key, label,
kind (dimension/measure), data type, allowed aggregations, and whether it
supports date bucketing. Use a column's key, never its label, in
run_explore_query.
Inputs: no named parameters. Returns: result
run_explore_queryA
Run a live, ad-hoc aggregate query against a whitelisted dataset — a preview,
never persisted. Pick dataset_key and every column value from
list_datasets's output. Returns rows, row_count, whether the result was
truncated (capped at 500 rows server-side), and a ranked list of recommended
chart types (bar/line/pie/kpi/table) for the shape of the result — use the
first recommendation as the visualization.type when building a report section
with create_draft_report/update_draft_report.
Inputs: dataset_key (required), limit, filters, measures, +1 more.
submit_reportA
Submit a draft/rejected report for review — moves it to 'submitted' status, visible to that domain's reviewers. Requires author-tier access to the report's target domain (Member, ReportGen, or domain-Admin).
Inputs: report_id (required).
update_draft_reportA
Edit a report while it's still in draft or rejected status — the backend 409s otherwise. Only fields you pass are changed.
Inputs: report_id (required), title, config_json.
view_custom_query_dashboardA
View a saved single-query custom_query report — its rows, chosen visualization, and a Claude-generated insight.
Inputs: report_id (required).
view_report_builder_dashboardA
View a saved multi-section report_builder report — every section's rows plus one Claude-generated insight synthesized across all sections. Works for any report the caller can view (draft they own, or published in a domain they have at least Readonly access to).
Inputs: report_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool occupies a distinct role in the dataset-query-draft-submit-view pipeline. The two view tools are clearly separated by dashboard_kind, and list_datasets vs run_explore_query are unambiguous as metadata listing vs live querying.
All tool names follow a consistent lowercase snake_case verb-first pattern (list_, run_, create_, update_, get_, submit_, view_). The compound noun suffixes for the two dashboard viewers are descriptive and predictable.
Eight tools cover the core report-builder workflow without redundancy or bloat. Each tool maps to a meaningful step in the process, making the set well-scoped for its domain.
The core workflow is covered: discover datasets, preview queries, create/update/fetch/submit reports, and view saved results. However, there is no list_reports tool to enumerate existing drafts or reports, and no delete/discard operation, which leaves tangible lifecycle gaps.
Maintenance
Related MCP Connectors
Provide seamless access to Appfolio Property Manager Reporting API through a standardized MCP serv…
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
MCP server for the Seline Analytics API
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- 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.25MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server that proxies MCP clients to Power BI, using your own Entra tenant and Azure subscription. It enables DAX queries, workspace listing, and dataset management while preserving user-specific row-level security.2MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for managing Microsoft Fabric Reports with lifecycle management, filtering, and content manipulation.8-
- AlicenseNot gradedqualityDmaintenanceMCP server for building and inspecting Power BI report visuals by editing PBIR files on disk, enabling page, chart, slicer, and layout management.MIT