PBIFORGE
PBIFORGE is an MCP server that generates, customizes, and exports Power BI dashboards (.pbit/.pbix) from various data sources — all running locally with no data rows sent to AI models.
Create dashboards from:
A local CSV file path (no API key required)
Raw CSV text pasted directly (no API key required)
Base64-encoded CSV data with optional branding image
Natural language descriptions via LLMs like Claude or GPT (API key required)
Live SQL databases (SQL Server, PostgreSQL, Oracle)
Customize reports:
Add specific visuals (bar charts, line charts, KPI cards, slicers) using plain English
Apply color themes extracted from reference images (PNG/JPG)
Edit styling via natural language (e.g. "dark navy background", "change primary color to #FF5733")
Add filters and slicers (year, dropdown, date range) to specific or all pages
Inspect the current report structure before further edits
Export as:
.pbittemplate file saved locally.pbixfile returned as base64Hosted public download URL (requires
PUBLIC_BASE_URLenvironment variable)
ReportForge PBI
Generate Power BI (.pbit) dashboards from CSV files or live SQL databases — locally, on your own machine, in seconds.
ReportForge profiles your data, designs a sensible dashboard layout (KPI cards + charts + filters), compiles it to a Power BI template, and writes the result to disk. Open the .pbit in Power BI Desktop and you have a working report.
Highlights
CSV upload — drop a single
.csv, get a.pbit. No Power BI required to generate it.Live SQL sources — SQL Server, PostgreSQL, Oracle. The generated
.pbitqueries the database on open; credentials are never embedded.Plain-English prompts — describe what you want ("bar chart company by revenue, line of growth over year"). Powered by Claude or GPT — bring your own API key. Without a key, ReportForge still produces a sensible default dashboard from a CSV profile; the prompt is ignored.
Layout from a reference image — drop in a screenshot of a dashboard you like. ReportForge reads the structure (card count, chart types, filter panel) and applies it to the generated layout, then adopts the color palette as the report theme.
Multiple chart types — bar, column, line, area, pie, donut, scatter, table. KPI cards. Slicers.
Browser UI — runs on
http://127.0.0.1:8000/. Local-only by default.MCP server — exposes the same tools to Claude Desktop over stdio for "/" prompts inside Claude.
Related MCP server: powerbi-mcp-local
Quick start
# 1. Clone
git clone https://github.com/twilize5/reportforge.git
cd reportforge-pbi
# 2. Install Python deps (creates .venv)
.\setup_local.ps1
# 3. Install pbi-tools.core somewhere on PATH or at C:\pbi-tools\
# Download: https://github.com/pbi-tools/pbi-tools/releases
# 4. Start the local server
.\run_api.ps1Open http://127.0.0.1:8000/ in your browser.
If you'd rather use ReportForge inside Claude Desktop, see LOCAL_SETUP.md for the stdio MCP setup.
The browser UI
Field | What it does |
Data source | Pick |
CSV file | Single CSV with a header row. Columns are profiled automatically (measures, dimensions, dates, geographic fields). |
SQL fields |
|
Prompt | Plain-English description of what you want to see. Requires an LLM key (see "AI assistance" below). Without a key the prompt is ignored and you get the deterministic default dashboard. |
Style reference image | Optional PNG/JPG. ReportForge reads the dashboard structure (number of KPI cards, chart types, filter panel presence) using Claude Vision and mirrors that layout in the generated report. Colors are also extracted and applied as the report theme. |
AI assistance | Required for prompts to take effect. Pick Anthropic/OpenAI and paste an API key, or pick local Qwen through Ollama. Only column names (not data rows) are sent to the model. |
The downloaded .pbit opens in Power BI Desktop, prompts for any data-source credentials, and renders the dashboard.
How prompts work
ReportForge always runs the deterministic dashboard builder (KPI cards, headline bar/line chart, donut for low-cardinality dims, second "Breakdowns" page when the dataset is rich). On top of that, if you supply an LLM key, your prompt is interpreted and additional visuals are appended.
What the LLM sees:
Your prompt
Column names + roles (
measure/dimension)Column semantic types (
temporal,geographic,categorical, etc.)Visuals the deterministic builder already produced (so it doesn't duplicate them)
What it does NOT see: any of your data rows.
The model returns a JSON list of chart specs (type, x-axis column, y-axis column, title); ReportForge validates each spec against the column profile and adds the ones that pass.
The response header X-ReportForge-Parser tells you which path ran for any given generate (llm:anthropic, llm:openai, llm:qwen, llm:<provider>-empty, no-key, or deterministic-only). The UI shows this under each "Report ready" message.
SQL data sources
ReportForge ships with lazy driver imports — the base install works for CSV-only use. Install drivers only for the databases you need:
# SQL Server (also needs the Microsoft ODBC Driver 17 or 18, installed system-wide)
.\.venv\Scripts\python.exe -m pip install pyodbc
# PostgreSQL
.\.venv\Scripts\python.exe -m pip install psycopg2-binary
# Oracle (thin mode - no Oracle client install required)
.\.venv\Scripts\python.exe -m pip install oracledbIn the UI, pick the source kind from the Data source dropdown. ReportForge:
Connects with the credentials you supply.
Pulls
SELECT TOP 1000(orLIMIT 1000) to profile column types, cardinality, and roles.Generates a Power Query M expression that Power BI Desktop will use to fetch the full dataset live.
Compiles everything into a
.pbit.
The credentials never make it into the .pbit file — Power BI Desktop will prompt for sign-in on first open. This is the standard Power BI Template behavior.
Example: SQL Server
Field | Example |
Server |
|
Database |
|
Schema |
|
Table |
|
Username/Password | Leave blank for Windows auth, fill for SQL auth. |
Example: free-form query
Paste a SELECT (with joins, filters, anything) into the Or: SELECT query box. ReportForge will profile the first 1000 rows of the result and target the same query in the generated M.
AI assistance
Provider | Model used | Where to get a key |
Anthropic | Claude Sonnet with fallbacks | |
OpenAI |
| |
Local Qwen | Auto-detected Ollama Qwen model, or | No API key required |
What gets sent to the model:
Your prompt
The list of column names + their inferred roles
The list of visuals already generated by the deterministic builder
Nothing else. Your data rows never leave your machine.
The key is cached in the browser tab's sessionStorage so you don't have to re-paste it on every generate. It's wiped when the tab closes.
For local Qwen, choose Local Qwen 2.5 (Ollama) in the provider dropdown. The Windows installer bundles a CPU-only Ollama runtime and will start it when ReportForge launches; qwen2.5:3b is pulled on first use if it is missing, so the first Qwen generation can take a few minutes and needs internet access. ReportForge calls http://127.0.0.1:11434 by default; override with QWEN_OLLAMA_URL or OLLAMA_HOST if your Ollama server runs elsewhere.
If you skip the key, ReportForge falls back to the deterministic dashboard builder only. Your prompt has no effect in that case — the dashboard is built purely from the column profile.
Style reference image
Drop any PNG/JPG (a screenshot of a dashboard you like, a brand mockup, a Tableau page). ReportForge runs two extractions in parallel:
Layout extraction (Claude Vision, requires Anthropic key) Reads the structural layout of the reference dashboard:
How many KPI/metric cards are visible → used as the KPI card count in the generated report
Which chart types are present (bar, column, line, area, donut, etc.) → influences chart type selection
Whether a right-side filter/slicer panel exists → adds or omits a slicer panel
Whether the KPI cards are in a left-column rail or a top-row grid → picks the matching layout template
Palette extraction (Claude Vision, or local Pillow fallback) Extracts the color scheme:
Primary, secondary, and accent colors
Page canvas background
Chart series palette (8-color rotation)
The layout extraction requires an ANTHROPIC_API_KEY. If no key is available, ReportForge still samples colors locally with Pillow and the layout falls back to the data-driven default.
API endpoints
All endpoints are local-only (127.0.0.1:8000).
Method + path | Purpose |
| Liveness probe. |
| The browser UI. |
| Multipart: |
| Multipart: |
| LLM-only path (requires |
| The MCP server, exposed over HTTP. Used by Claude Desktop and other MCP-aware clients. |
For Claude Desktop integration over stdio, point the launcher at run_mcp_stdio.ps1 — see LOCAL_SETUP.md.
Windows installer (single .exe for end users)
A double-clickable installer is available for users who don't want to run setup_local.ps1. It bundles Python, all dependencies, the FastAPI app, and pbi-tools.core into one .exe. See installer/README.md for the build process. End-user install flow:
Download
ReportForge-PBI-Setup-1.0.3.exe(or the latest version).Run it (admin required — installs into
Program Files).Start Menu → ReportForge PBI. The server starts and your browser opens automatically.
User data (generated reports, sources, sessions) lives at
%LOCALAPPDATA%\ReportForge\and survives reinstall/uninstall.
Power BI Desktop External Tool button
Optional. Adds a ReportForge PBI button to the External Tools ribbon in Power BI Desktop. See EXTERNAL_TOOL_SETUP.md.
Some tenants block External Tools registration via Fabric tenant policy. If the ribbon button doesn't appear after registering, the browser UI still works — just open http://127.0.0.1:8000/ directly.
Architecture (one screen)
┌──────────────┐
CSV / SQL → ┤ data_profiler / data_sources ┤ → DatasetProfile
└──────────────┘
│
▼
build_intent_from_profile (deterministic)
│
│ + prompt parser (regex OR LLM)
│ + image layout hint extractor (Claude Vision)
│ + image palette extractor (Claude Vision / Pillow)
▼
ReportIntent (Pydantic)
│
▼
build_bim_from_profile → semantic model (BIM JSON)
build_m_for_source → Power Query M
build_layout_from_intent → report layout (visuals + theme)
│
▼
pbi-tools.core compile → .pbit
inject_data_mashup (DataMashup binary)
inject_report_layout (Report/Layout)
│
▼
.pbit fileKey files:
main.py— FastAPI app, endpoints, static UI mount.orchestrator.py— pipelines (pipeline_from_csv,pipeline_from_source).data_profiler.py— CSV profiler.data_sources.py— DB profilers + M generators for MSSQL / Postgres / Oracle.auto_intent.py— deterministic intent + layout builder, regex prompt parser.llm_intent.py— LLM-driven prompt parser (Anthropic + OpenAI).image_analyzer.py— palette extraction and layout hint extraction from reference images.file_writer.py— writes the project tree, injects DataMashup + Report/Layout.mcp_server.py— MCP tools for Claude Desktop.static/index.html— browser UI.
Troubleshooting
.pbit won't open / "An error occurred while opening the file".
Usually a stale generation in generated_reports/. Delete and regenerate. If it persists, check the server logs — pbi-tools.core errors usually show up there.
External Tools button doesn't appear in Power BI Desktop.
Most often a Fabric tenant policy. See the troubleshooting section in EXTERNAL_TOOL_SETUP.md.
LLM call fails silently.
When the LLM call errors or returns an empty visuals list, ReportForge falls back to the deterministic builder and surfaces llm:<provider>-empty in the X-ReportForge-Parser response header (visible in the UI status message). Double-check the key value, the provider dropdown, and that openai is installed (pip install openai) if you picked OpenAI.
SQL profiling fails with "pyodbc/psycopg2/oracledb is required". Install the relevant driver into the venv (see SQL data sources).
Generation succeeds but the dashboard looks plain blue, not like my reference image.
The local Pillow palette extractor is more conservative than the Anthropic vision path. If you have an ANTHROPIC_API_KEY set, the vision path gives better color results. Or open the resulting .pbit and tweak the theme manually.
Reference image supplied but the layout doesn't match it.
Layout extraction requires an ANTHROPIC_API_KEY — without one, only colors are sampled and the layout falls back to the data-driven default. Check that the key is set and that the reference image clearly shows the dashboard structure (card tiles, chart panels, filter sidebar).
Project state
This is the local-first incarnation of ReportForge. Railway deployment is not the supported path right now — everything is designed to run on your machine, talk to local CSVs and databases, and write .pbit files into generated_reports/.
The roadmap (see .claude/plans/) covers:
Phase 1: SQL connectors (✅ this release).
Phase 2: joined multi-table models with auto-relationship inference.
Phase 3: read the model out of an open Power BI Desktop session via a .NET helper.
Available Tools
13 toolsadd_filterB
Add a slicer or filter to the report. Examples:
"add a Year slicer to the Overview page"
"add a Region dropdown filter"
"add a date range filter for all pages" page_name: specific page, or None for all pages
Inputs: session_id (required), filter_description (required), page_name. Returns: object
add_visualA
Add a visual to an existing report session. description: plain English e.g. "bar chart of units sold by product category" page_name: which page to add to (default: Overview)
Inputs: session_id (required), description (required), page_name. Returns: object
apply_image_themeC
Extract color palette from a dashboard image and apply it as the report theme. image_base64: base64-encoded image string media_type: image/png or image/jpeg
Inputs: session_id (required), image_base64 (required), media_type. Returns: object
create_dashboardA
Create a complete Power BI dashboard from a local dataset path. USE THIS TOOL when the user says "create a dashboard/report from this dataset" and provides a local file path. Prefer this over create_report because this reads real data rows and does not require an Anthropic API key.
Supports CSV files. Returns a local .pbit file_path, not base64.
Inputs: dataset_path (required), title. Returns: object
create_from_csvA
Create a Power BI dashboard from a CSV file. Auto-generates KPI cards, bar chart, line chart, pie chart, and slicer — no prompt required. csv_base64: base64-encoded CSV bytes. filename: original filename (used for table naming in the data model). prompt: optional report title override (e.g. "Q4 Sales Overview"). image_base64: optional branding image (base64) to extract theme colors from. Returns: session_id, pbix_base64 (save as .pbit), report_title, columns_detected, domain.
Inputs: csv_base64 (required), prompt, filename, image_base64. Returns: object
create_from_csv_file_pathB
Create a Power BI dashboard from a CSV file already on this computer. Preferred for Claude Desktop because it avoids putting large CSV/base64 data into the conversation context.
Inputs: file_path (required), prompt. Returns: object
create_from_csv_textB
Create a Power BI dashboard from raw CSV text. This is easier to use from Claude Desktop than base64 input. Does not require an Anthropic API key unless image theming is used elsewhere.
Inputs: csv_text (required), prompt, filename. Returns: object
create_reportA
Create a new Power BI report from a natural language description. Do NOT use this when the user provides a CSV/dataset file path; use create_dashboard instead. This tool needs a valid Anthropic API key. Returns a session_id to use in all subsequent tool calls. Example: "monthly sales by region with YoY comparison for retail team"
Inputs: description (required). Returns: object
edit_stylingB
Edit report styling via natural language. Examples:
"make all charts use a dark navy background"
"change primary color to #FF5733"
"use a minimal flat style with no borders"
Inputs: session_id (required), instruction (required). Returns: object
export_pbit_fileA
Compile the current session and save the .pbit locally. Claude Desktop should prefer this over export_pbix to avoid huge base64 output.
Inputs: session_id (required). Returns: object
export_pbit_urlA
Compile the current session, save the .pbit on the hosted server, and return a public download URL. Set PUBLIC_BASE_URL on Railway for this tool.
Inputs: session_id (required). Returns: object
export_pbixA
Compile the current session into a .pbix file and return it as base64. The base64 string can be decoded and saved as report.pbix.
Inputs: session_id (required). Returns: object
get_report_stateB
Return the current report structure for inspection. Useful for understanding what has been generated before editing.
Inputs: session_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
The creation tools (create_dashboard, create_from_csv, create_from_csv_file_path, create_from_csv_text, create_report) have overlapping purposes, with subtle distinctions that may confuse an agent. Other tools like add_filter, add_visual, and export variants are clearer.
All tool names follow a consistent verb_noun pattern using underscores (e.g., add_filter, create_report, export_pbit_file). Even compound names like create_from_csv_file_path maintain the pattern, with no mixing of conventions.
13 tools cover creation, editing, theming, export, and inspection, which is well-scoped for a report generation server. Not over or under-loaded.
Covers most CRUD-like operations: create reports from various sources, add visuals/filters, edit styling, export results, and inspect state. Minor gap: no tools for deleting visuals, filters, or pages, but core workflows are supported.
Maintenance
Related MCP Connectors
Forge designed Power BI projects (.pbip) from your agent, bound to your own semantic model.
LLM Orchestration Agent (Mcp)
MCP server for Qwen Image 3 AI image generation
LLM Orchestration MCP Agent
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
- AlicenseCqualityCmaintenanceLocal-first MCP server for Power BI Desktop automation. Automate semantic model changes, DAX, Power Query, Excel, and report layout from MCP-capable AI clients.1002MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Power BI — local PBIX file analysis, cloud API operations, report export, and semantic model extraction from Power BI Desktop.30 npm1MIT
- AlicenseBqualityBmaintenanceMCP server for interacting with local Power BI Desktop and .pbip projects, enabling DAX queries, model documentation, measure editing, and PBIR visual management via natural language.90130 PyPI1Apache 2.0