Skip to main content
Glama
BI Portal Report Builder MCP Server

BI Portal Report Builder MCP Server

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 token field (pat_...) is shown once — copy it into BI_PORTAL_TOKEN.

  • fixed — acts as a standing service identity (e.g. a FinanceReportGen-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 token field (svc_...) is shown once — copy it into BI_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 needed

Run directly over stdio (what most desktop MCP clients expect):

python -m mcp_bi_portal.server

Example 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

list_datasets

GET /api/explore/datasets

run_explore_query

POST /api/explore/run

create_draft_report

POST /api/reports

update_draft_report

PATCH /api/reports/{id}

get_report

GET /api/reports/{id}

submit_report

POST /api/reports/{id}/submit

view_report_builder_dashboard

GET /api/dashboards/report-builder

view_custom_query_dashboard

GET /api/dashboards/custom-query

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 tools
create_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

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      25
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for building and inspecting Power BI report visuals by editing PBIR files on disk, enabling page, chart, slicer, and layout management.
      MIT