Back to Browse

Vilsem MCP Server

by Bcsnpc
Developer ToolsScan in ProgressMCP RegistryLocal
Free

Server data from the Official MCP Registry

Author custom Power BI visuals on your live Desktop model: preview, self-review, commit to PBIP.

About

Author custom Power BI visuals on your live Desktop model: preview, self-review, commit to PBIP.

Security Report

0.0
Use Caution0.0Moderate Risk

24 tools verified · Open access · No issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Remote servers are capped at 8.0 because source code is not available for review. The score reflects endpoint verification only.

How to Install

Install command not verified. See the repository for install instructions.

View repository

Documentation

View on GitHub

From the project's GitHub README.

vilsem-mcp

Author Vilsem custom visuals from chat into an existing Power BI report, using real model data and declarative specifications.

vilsem-mcp doesn't make charts. Claude Code and Codex make charts; vilsem-mcp gives them your model, real data, eyes, and a safe pen. The MCP contains no model and needs no LLM API key. The calling agent's own service or account may have its own costs.

See what it can build: the Vilsem Prompt Book has 104 visuals on Contoso, AdventureWorks and cricket data, each with the exact prompt that built it. Copy a prompt, point your agent at your own model and adapt the fields.

This is the custom-visual layer for agentic Power BI authoring. Use it alongside Microsoft's Power BI Report skill for native visuals and the Power BI Modeling MCP for model changes. The shared, installed renderer executes trusted application code; the authored spec is declarative JSON, not executable source.

Contents

Release status: 0.9 evaluation

Read SECURITY.md for local-mode boundaries, AI-provider disclosure, sample opt-out and vulnerability reporting.

Current release: vilsem-mcp 0.9.3, @vilsem/core 0.8.3, Vilsem Renderer 4.46.0.0. Releases are built and published by CI, with SHA-256 checksums and verifiable build provenance. These are evaluation prereleases, suitable for testing on copies of your reports. Production readiness, certification and exhaustive cross-target parity have not been established. The previous stable release remains 0.6.

Read what was verified, known failures and incomplete checks before relying on a result. Passing tests do not mean every visual, property, dataset, report interaction or export works. This README on main includes live checks performed after the original release archive was built; existing release tags and assets are not rewritten.

Why not just ask Claude Code / Codex directly?

For a custom visual outside Power BI's native catalog:

WorkAgent without this custom-visual layerWith vilsem-mcp
Understand the modelFind a connector, inspect fields and recover calculation contextget_schema summary/full with calculations, statistics and relationship context
Choose an analytical designWork out question, grain, units and alternativesStill the agent's decision; design_visual and the design guide supply a structured brief
Use real numbersImplement a query bridge and field normalizationRead-only local Desktop DAX and actual field bindings
See and improve a draftBuild a renderer and screenshot pipelinepreview_visual, critique and shared-data preview_variants
Put it in a reportImplement, package and import a custom visual and configure queriescommit_visual writes one supported custom visual and any missing renderer registration
Edit the visual a month later, in a new chatFind the old source/chat, re-explain, rebuild, repackage, re-import and rebindRead the report's spec: "make the Sankey labels bigger"; preview a small patch
What runs inside the reportEach separately authored compiled visual's implementationOne shared renderer plus plain declarative specifications
Security reviewReview each executable implementation and its dependenciesReview the shared renderer/dependencies and the bounded format; report policies still apply

This does not imply native Power BI visuals require custom coding. Microsoft's companion Report skill handles those.

Three authoring layers

  1. Composition: a supported chart type and configuration; the smallest spec and maintenance cost.
  2. Template: ECharts structure, declared slots, parameters and bounded transforms; more control, with explicit layout and unit responsibilities.
  3. Expression series: a closed JSON AST describes bounded custom geometry. One trusted interpreter runs it in previews and the renderer; arbitrary renderItem/JavaScript is refused. See vilsem://docs/expression-language.

Quick start (Windows)

You can use this with any report; the shipped examples are not tied to the QA model. Use your own fields discovered by get_schema.

Using Claude Code? Install in two lines instead of steps 2–5. In a Claude Code session:

/plugin marketplace add bcsnpc/vilsem-mcp
/plugin install vilsem@vilsem-mcp

VS Code extension: type /plugins, add bcsnpc/vilsem-mcp on the Marketplaces tab, then click Install on vilsem. Claude desktop app (Code tab): click + next to the prompt box → Add plugins. A plugin installed in any of these is available in the others on the same PC.

This adds the MCP server and the Vilsem playbook skill. The first start downloads and verifies the pinned release (about 30 seconds, once). Then continue at 6. Prepare a test report. Details: Claude Code plugin.

1. Prerequisites

  • Node.js 22.12+, 24, or 26+
  • Power BI Desktop (August 2026 or later recommended for live external reload)
  • A local MCP-capable agent: Claude Code, Claude Desktop, Codex or GitHub Copilot

The MCP server and Desktop must run on the same Windows machine for Desktop mode. The Vilsem Electron app is not required. There is no npm-registry publication; always install a pinned GitHub release.

2. Install the pinned release

In PowerShell (no Git or source checkout needed):

node --version
$vilsemDir = Join-Path $env:USERPROFILE 'vilsem-mcp'
New-Item -ItemType Directory -Force -Path $vilsemDir | Out-Null
npm.cmd install --prefix "$vilsemDir" "https://github.com/bcsnpc/vilsem-mcp/releases/download/v0.9.3/vilsem-mcp-0.9.3.tgz"
  • npm.cmd avoids PowerShell execution-policy errors. If node is missing, reopen the terminal after installing Node.
  • The warning install-scripts … vilsem-mcp (prepare: npm run build) is harmless for the release tarball: dist/ is prebuilt.
  • Installation downloads core 0.8.3 and renderer 4.46 automatically; no application-path environment variable is needed.

3. Verify the download (recommended)

Compare the archive against the published checksums for the release:

$tgz = Join-Path $env:TEMP 'vilsem-mcp-0.9.3.tgz'
Invoke-WebRequest "https://github.com/bcsnpc/vilsem-mcp/releases/download/v0.9.3/vilsem-mcp-0.9.3.tgz" -OutFile $tgz
(Get-FileHash $tgz -Algorithm SHA256).Hash.ToLower()
# Compare with the vilsem-mcp-0.9.3.tgz line in SHA256SUMS-0.9.3.txt on the release page
# Optional, with the GitHub CLI: confirm the archive was built by this repository's release workflow
gh attestation verify $tgz --repo bcsnpc/vilsem-mcp

If you verified a local copy, you can install from it instead: npm.cmd install --prefix "$vilsemDir" "$tgz".

4. Record the two paths your agent needs

$server = (Join-Path $vilsemDir 'node_modules/vilsem-mcp/dist/index.js') -replace '\\','/'
$node   = (Get-Command node).Source -replace '\\','/'
Test-Path $server   # must be True
$server; $node

Use $server in the client configuration below. If the client cannot find node, use the full $node path as command.

5. Connect your agent

Pick your client in Connect your agent, then restart the client and confirm the Vilsem tools appear. Network/UNC paths and file URLs are refused in all path parameters; remote template/browser environment settings are ignored with a startup warning. Use local drive paths.

A stdio server does not open a website; the MCP client starts it.

6. Prepare a test report

  • Save a test copy of the complete report project, preserving the relative report/model folder structure.
  • A .pbix must first be saved as a PBIP project in Desktop. MCP does not patch a PBIX binary.
  • The report must use enhanced PBIR (<name>.Report/definition/pages/). Convert it in Desktop if needed.
  • Enable Detect and reload external PBIP changes (see Desktop setup) and restart Desktop.
  • Optionally create an empty test page in Desktop, then save.
  • Let the report finish loading in Desktop before the agent connects. Large models take a minute; until then the connection reports that no model is loaded yet.
  • On large models the agent should call get_schema with profile:false first, then profile only the tables it needs. Default profiling stops after about 20 seconds.

7. Build, commit and check

  1. Give the agent the absolute .Report folder path (not the .pbip or .pbix) and use the first test prompt.
  2. Inspect the real-data preview, then let the agent commit to an existing page.
  3. Follow the reload rules: the first Vilsem visual in a report needs a close-and-reopen without saving; later commits only need the external-changes prompt.
  4. Confirm real numbers, selection, slicers, hover/context menus, resize and save/reopen yourself. Existing native visuals should remain intact. validate_visuals checks Vilsem objects only.
  5. Before publishing or sharing, make sure the report has no visual-scoped measures. See Measures: prototype vs publish.

playwright-core is optional and loaded only for browser motion capture. If unavailable, static previews still work; motion:auto falls back to sampled states with a warning and motion:browser returns an explicit error.

For animated browser previews, install Chrome/Edge/Chromium or set VILSEM_PREVIEW_BROWSER_PATH in the MCP server environment. Static previews do not need a browser.

Connect your agent

Vilsem is not tied to one client. The same installed server and prompts work with Claude Code, Claude Desktop and Codex. The agent designs the visual; Vilsem supplies model access, validation, previews and scoped report edits.

Vilsem is a local stdio server, not a hosted HTTP connector, because it must reach Power BI Desktop on your PC. For Claude there are two packaged ways to install it with no manual configuration: the Claude Code plugin and the Claude Desktop extension. Pasting a local path into a browser-only chat does not connect it. For Desktop mode the server must run on the Windows machine containing the open Power BI model; a cloud/remote agent needs a local execution connection. Client setup follows official documentation; not every client UI version has been tested end to end.

Claude Code plugin (easiest)

Needs Windows, Node.js 22.12+ with npm, and Claude Code. The plugin installs the MCP server and the Vilsem playbook skill; quick-start steps 2–5 are not needed. In a Claude Code session:

/plugin marketplace add bcsnpc/vilsem-mcp
/plugin install vilsem@vilsem-mcp

Or in one step on Claude Code 2.1.275 or later: /plugin install vilsem --marketplace bcsnpc/vilsem-mcp. From a terminal, use claude plugin marketplace add bcsnpc/vilsem-mcp then claude plugin install vilsem@vilsem-mcp. Restart Claude Code or run /reload-plugins, then check /mcp.

  • VS Code extension: type /plugins in the prompt box to open Manage plugins. On the Marketplaces tab add bcsnpc/vilsem-mcp, then on the Plugins tab click Install on vilsem.

  • Claude desktop app, Code tab (local session): click + next to the prompt box → Add plugins (or Plugins → Browse plugins). Plugins are not available in cloud or WSL sessions, and Vilsem needs Power BI Desktop on the same Windows PC anyway.

  • The terminal, the VS Code extension and the desktop app's local sessions share the same settings, so a user-scope install in one is available in the others. Start a new session (or run /reload-plugins) to pick it up.

  • On its first start the plugin downloads the pinned, CI-built release archive, verifies its SHA-256 against the value in claude-plugin/launcher.mjs (the same value as the release's SHA256SUMS file), and installs it with its locked dependencies into the plugin's data folder. This takes about 30 seconds once; later starts take about 2. If /mcp reports a failed start the first time, reconnect it there.

  • The skill is available as /vilsem:vilsem-powerbi-visuals.

  • Update with /plugin marketplace update vilsem-mcp, then /plugin update vilsem@vilsem-mcp.

  • If you also added Vilsem manually (below), remove one of them to avoid duplicate tools.

Claude Desktop extension (.mcpb)

From 0.9.2, each release includes vilsem-mcp-<version>.mcpb, a one-file Claude Desktop extension. CI builds it, lists its checksum in SHA256SUMS, and covers it with build provenance. Download it, then double-click it (or drag it into Claude Desktop → Settings → Extensions) and approve the install. It bundles the server and its locked dependencies; Claude Desktop provides Node.js. Windows only.

Manual configuration

All examples use C:/Users/YOUR_NAME/.... Replace it with your profile path, or paste the $server value printed in step 4. Use forward slashes.

Claude Code

Option A — with the claude CLI:

claude mcp add --scope user --transport stdio vilsem -- node "C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"
claude mcp list

--scope user makes it available in every project on this machine. Omit it to use the default local (current project) scope.

claude not on PATH? This is common when Claude Code is used only through the VS Code extension or desktop app. Either run the bundled binary directly:

$claude = Get-ChildItem "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-*\resources\native-binary\claude.exe" | Select-Object -Last 1
& $claude.FullName mcp add --scope user --transport stdio vilsem -- node "C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"

or use Option B.

Option B — without the CLI (edit JSON):

  • All projects (user scope): add a top-level mcpServers key to %USERPROFILE%\.claude.json. The file already contains other settings; merge this key in and keep everything else. Close Claude Code before editing so it does not overwrite the file.
  • One project (shared): create .mcp.json in the project root. Claude Code asks you to approve project servers the first time.

The entry is the same in both files:

{
  "mcpServers": {
    "vilsem": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"]
    }
  }
}

If mcpServers already exists, add only the "vilsem": {...} entry inside it. Validate the file afterwards:

Get-Content "$env:USERPROFILE\.claude.json" -Raw | ConvertFrom-Json | Select-Object -ExpandProperty mcpServers

Agents installing this for a user: prefer Option A. If the CLI is unavailable, do a JSON parse → set mcpServers.vilsem → write, with a backup of the original file. Do not hand-build the file with string concatenation or escaped one-liners.

Restart Claude Code (VS Code: Developer: Reload Window), then run /mcp to confirm vilsem is connected. Run the server in Windows for Desktop model discovery; a WSL/container-only server is not the tested Windows ADOMD setup. See Claude Code's MCP documentation.

Claude Desktop

Use Claude Desktop's developer Edit Config control to open the actual claude_desktop_config.json, then merge this entry into mcpServers, keeping other servers:

{"mcpServers":{"vilsem":{"command":"node","args":["C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"]}}}

Fully quit and reopen Claude, then check that the Vilsem tools appear. This is manual local-server configuration, not a remote connector or an extension. See the local-server walkthrough and Claude's local MCP overview.

Codex

Add to ~/.codex/config.toml or a trusted project's .codex/config.toml:

[mcp_servers.vilsem]
command = "node"
args = ["C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"]
startup_timeout_sec = 60
tool_timeout_sec = 600

The longer tool timeout accommodates schema profiling and real-data previews on larger models. See the Codex MCP configuration documentation.

GitHub Copilot (VS Code agent mode)

For VS Code's editor-managed MCP configuration, create .vscode/mcp.json in your workspace (or use the user-level MCP configuration). This file uses servers, not mcpServers:

{
  "servers": {
    "vilsem": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/YOUR_NAME/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js"]
    }
  }
}

Trust the folder, start the server when VS Code asks, switch Copilot Chat to Agent mode, and check that the tools icon lists the Vilsem tools. Ask the agent to call get_playbook without arguments before authoring. Copilot does not read MCP resources automatically; the playbook comes through this tool.

Configuration compatibility: newer Copilot harnesses also have a native .mcp.json / user mcp-config.json format using mcpServers. Do not mix that format with .vscode/mcp.json. See Microsoft's MCP configuration reference for the active harness in your VS Code version.

ClientStatusCoverage
Claude CodePartially testedContoso authoring field run. Fresh-install run of 0.9.1 on a blank 10M-row Contoso copy (2026-11-12): install, checksum, playbook, schema, previews with critique, two commits; first-visual close/reopen and later Apply both worked in Desktop. Exhaustive client/version coverage not established.
CodexPartially testedRecorded Desktop/Service QA workflows; exhaustive coverage not established.
Claude DesktopNot fully testedSetup documented; full current-version build run pending.
GitHub CopilotPartially tested0.8.2 with the auto-selected model (GPT-6 Luna): connected, retrieved the playbook through get_playbook (when prompted), previewed before committing and bound model measures. It repeated the close-and-reopen step for later commits; 0.9.0 makes the returned nextStep the explicit instruction.

Other MCP clients

The client must support local stdio tools and image results. MCP resources are optional; get_playbook delivers the playbook through a tool. Use the same node <server path> command. Individual clients are not certified here.

Optional: install the playbook as a native skill

Server instructions tell agents to call get_playbook without arguments first, then request on-demand sections. Existing vilsem://skill/* resources remain available for clients that can read them. To also install it as a native skill:

node "$env:USERPROFILE/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js" install-skill --target claude
node "$env:USERPROFILE/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js" install-skill --target codex
node "$env:USERPROFILE/vilsem-mcp/node_modules/vilsem-mcp/dist/index.js" install-skill --target "C:/Team/agent-skills"
  • claude → ~/.claude/skills/vilsem-powerbi-visuals; codex → ~/.agents/skills/vilsem-powerbi-visuals (OpenAI documentation). Pass an explicit skills-root directory for older clients or custom locations.
  • No target defaults to claude. With no subcommand, the CLI starts the MCP server.
  • Existing skill folders are refused unless --force is supplied; force replaces only packaged files and keeps unrelated files. Linked/non-regular destinations are refused.
  • No install hook writes into your home directory; only this explicit subcommand does. Skill installation does not configure the MCP connection.

One-shot from the pinned release without a prior install:

npx.cmd --yes --package=https://github.com/bcsnpc/vilsem-mcp/releases/download/v0.9.3/vilsem-mcp-0.9.3.tgz vilsem-mcp install-skill --target claude

Alternative: global install from the Git tag

npm install -g git+https://github.com/bcsnpc/vilsem-mcp.git#v0.9.3
vilsem-mcp
# Or: npx --yes --package=git+https://github.com/bcsnpc/vilsem-mcp.git#v0.9.3 vilsem-mcp

The process serves stdio JSON-RPC; diagnostics go to stderr. With a global install, point your client's command at vilsem-mcp instead of node <path>.

First test: generate a new visual from scratch

Replace the path and analytical request, then send this to your agent:

Use the vilsem MCP with my open test report:
C:/Reports/MyTest/MyTest.Report

Connect using this report's binding and inspect get_schema. Author a NEW
.vilsem-visual.json specification from scratch for a useful category-versus-
measure visual using actual fields from this model. Do not reuse a shipped
template or copy example business values. Explain the chosen grain and units.
Run validate_spec, explain_visual and preview_visual with real data. Inspect
and improve the result. Use list_pages to choose the existing test page and
avoid overlapping its visuals. Then commit the new Vilsem visual, read it back
and run validate_visuals. Preserve the model, native visuals and manual format
settings. Tell me when to accept reload/reopen and what to check in Desktop.

More prompts — trends with prior periods, dual-axis visuals, full pages, formatting edits, hierarchies, Sankey and custom geometry — are in the prompt cookbook. Replace only the marked placeholders and use fields from get_schema; no prompt relies on QA table names, a fixed Desktop port or embedded business values.

Measures: prototype vs publish

A Vilsem spec can declare visual-scoped measures (spec.measures). They are ideal for iterating, because they need no model change and no Desktop reload. But once committed, Power BI stores them as report-level extensions on the visual, and that has consequences:

Where the report is usedVisual-scoped measuresModel measures
Desktop and Power BI Service (signed in)WorksWorks
Build pane field wellsEmpty for those fieldsShown normally
Publish to web (public embed)Fails with PowerBIAnonymousExtensionSchemaException on every affected visualWorks
Reuse in other visuals / by other authorsNot reusableReusable

Recommended practice:

  1. Prototype with spec.measures while designing and previewing.
  2. At commit time (or before publishing), write each measure into a model measures table and bind the visual to the model measure (Measure field, not NativeMeasure). Do this in the same step, so nothing has to be reworked later.
  3. Vilsem itself never writes the model. The agent adds the measures to the model's TMDL (with the user's agreement) or uses the Power BI Modeling MCP. Model changes need a Desktop close and reopen to load, so batch them: one reopen per batch of visuals, not per visual.

Call get_playbook with section:"9a" (or read vilsem://skill/powerbi-visuals, section "Measures for shareable reports") for the exact agent procedure.

Desktop setup and reload rules

In Desktop, open File → Options and settings → Options → Preview features, enable Detect and reload external PBIP changes, and restart Desktop. Microsoft documents this preview feature and its limits in external project editing. Earlier Desktop versions require a close/reopen after every external change.

Walkthrough

  1. Open your semantic model in Desktop. Prefer connect_model with source:{kind:"report",reportDir:"C:/Reports/MyTest/MyTest.Report"} to follow the report's binding; otherwise use source:{kind:"desktop"} (pass a port if more than one model is open). Online models are disabled by default in 0.9.
  2. Call get_schema and choose existing dimensions/measures, or declare query-only spec.measures for prototyping. With scoped measures, pass connectionId to validation, explanation and commit as well as preview. Use run_dax to verify the data.
  3. Call list_templates, read vilsem://docs/spec-format, then validate_spec, explain_visual and preview_visual. Check the PNG and option before writing.
  4. Call list_pages, choose a position without overlap, then commit_visual with the report folder, page folder name, a new visualName, spec, bindings and layout.
  5. Reload Desktop (rules below), inspect the rendered result and call validate_visuals. Save from Desktop when satisfied.

Reload rules

SituationWhat to do in Desktop
Before any external writeSave your Desktop work first.
First Vilsem visual in a report (rendererRegistered:true)Close without saving and reopen the .pbip. Renderer registration lives in report.json, which Desktop does not live-reload. Alternative: import the bundled renderer in Desktop and save before the first commit.
New pages added outside DesktopTry Apply external changes first; if the page does not appear, close without saving and reopen.
New or changed model measures (TMDL)Close without saving and reopen. External-change reload covers report files, not the semantic model.
Later visual commits/updatesAccept the external changes prompt.
AlwaysNever save stale Desktop state over external changes.

The bundled renderer is at <vilsemDir>/node_modules/@vilsem/core/assets/renderer.pbiviz.

Experimental: online models (disabled by default)

0.9.x supports local Desktop models only. Fabric, Power BI Service, report byConnection and SSAS are disabled before any authentication or connector call. Open the model locally and use kind:"report" with a byPath report, or kind:"desktop".

For developer investigation only, VILSEM_ENABLE_ONLINE=1 restores the existing online connector and prints a startup warning. It is unsupported/experimental and can authenticate, cache tokens and contact Microsoft or the report endpoint.

Desktop: requires Windows and a running Power BI Desktop model. Core identifies the Desktop Analysis Services process and reads its workspace port file. Pass source.port if multiple instances are open. ADOMD/XMLA uses your Windows identity; no cloud login is needed. Ports change each time Desktop reopens; never reuse a port from another session.

Fabric: configure these environment variables on the MCP server process:

  • Service principal: AUTH_MODE=service_principal, FABRIC_TENANT_ID, FABRIC_CLIENT_ID, FABRIC_CLIENT_SECRET.
  • User login: AUTH_MODE=device_code (default). Login instructions go to stderr; complete Microsoft's device-code login in your browser. Only the refresh token is cached under ~/.vilsem/auth/, scoped to tenant/client/resource, in a 0700 directory and atomic 0600 file. Windows uses the user-profile ACLs; POSIX modes are not Windows ACLs.
  • Optional FABRIC_ACCESS_TOKEN for an externally supplied short-lived token. Refresh requires another configured credential flow.

No credentials are read from another repository's .env or Electron workspace store. Set credentials in your MCP client's server environment. Core also preserves setInteractiveTokens for Electron PKCE login. Fabric credentials do not transfer to a new machine.

Connecting from an existing report binding

connect_model with source:{kind:"report",reportDir:...} follows the report's definition.pbir without changing it:

  • datasetReference.byPath: core matches the local semantic-model path to an open Desktop session. It matches the right Desktop window by its .pbip project, so other open reports don't interfere. If the model is still loading, the connection says so; wait and retry. {kind:"desktop"} without a port auto-detects a single open model; with several open, the error lists each session's port and .pbip path. With Desktop closed it reads the local TMDL or BIM definitions and returns schemaOnly:true. Schema-only connections cannot run DAX or preview live values; open the model and reconnect.
  • datasetReference.byConnection: disabled by default in 0.9. With the unsupported VILSEM_ENABLE_ONLINE=1 override, a Power BI XMLA URL identifies the workspace and semantic model. Core resolves them through the configured Fabric credentials. It does not try to discover a local Desktop port. The identity needs access to list the workspace and model, execute queries and inspect its definition. Windows-integrated SSAS bindings use the local ADOMD bridge and Windows identity; cloud credentials are never forwarded to arbitrary servers.

Find the port of an open Desktop model (the most recently opened report is listed first):

Get-ChildItem "$env:LOCALAPPDATA\Microsoft\Power BI Desktop\AnalysisServicesWorkspaces","$env:USERPROFILE\Microsoft\Power BI Desktop Store App\AnalysisServicesWorkspaces" -Directory -ErrorAction SilentlyContinue |
  Sort-Object LastWriteTime -Descending | ForEach-Object {
    $f = Join-Path $_.FullName 'Data\msmdsrv.port.txt'
    if (Test-Path $f) { '{0}  opened {1}' -f (Get-Content $f -Encoding Unicode -Raw).Trim(), $_.LastWriteTime }
  }

Old workspace folders can remain after Desktop closes; if a port refuses the connection, try the next one. Ports change every time Desktop reopens.

Quoted connection-string values are supported. Passwords and impersonation settings embedded in the report are ignored; configure authentication on the MCP server. Missing or ambiguous targets fail explicitly. commit_visual writes only the Vilsem visual in the selected local report; it does not change the binding, semantic model, native visuals or report policies.

Agent workflow

Until a session successfully calls get_playbook, results of connect_model, get_schema, preview_visual, preview_variants and commit_visual include a playbookHint. It does not block the tool.

run_dax only accepts DAX queries starting with EVALUATE/DEFINE; DAX queries cannot modify the model. XMLA/TMSL commands are rejected. Leading --, // and block comments are supported without altering quoted strings.

connect_model → get_schema → design_visual prompt → validate_spec → explain_visual → preview_visual with critique → compare variants/iterate → list_pages → commit_visual → Desktop reload and native checks. Never commit without a preview. Read vilsem://docs/design-guide and vilsem://docs/workflow.

For edits: list_visuals → read_visual → update_visual(dryRun:true) → inspect before/after and confirm when not already authorized → update_visual(dryRun:false, etag) → reload and verify. The report folder is the source of truth. Manual format-pane values win over authored formatting and survive updates unless resetFormatting:true is explicit.

Tools and resources

Tools (20): get_playbook, connect_model, get_schema, run_dax, list_templates, save_template, delete_template, validate_spec, explain_visual, preview_visual, preview_variants, list_pages, list_visuals, read_visual, diff_visual, update_visual, commit_visual, validate_visuals, extract_design_tokens, compare_preview. Prompt: design_visual. Resources: vilsem://skill/*, vilsem://templates/<template-id>, vilsem://docs/spec-format, vilsem://docs/design-guide, vilsem://docs/workflow, vilsem://docs/expression-language.

  • get_playbook is read-only and offline. No arguments returns a compact core plus an index. Fetch 9a, commit, edit, known-issues, gotchas, pbir-pages, cookbook:<slug> or art:<slug> as needed. cookbook and art list available patterns; all returns the complete skill. Sections are read from packaged Markdown at runtime. The four skill resources remain available, including vilsem://skill/data-art-recipes.
  • get_schema supports samples:false or the VILSEM_SCHEMA_SAMPLES=0 environment default to omit column samples while preserving counts/ranges. It defaults to summary (no expressions or relationship graph); use full for business calculation and join semantics. Exact cardinality/BLANK share/ranges are cached for 60 seconds with at most 10 samples. Full profiling of large models can take minutes; prefer targeted run_dax. Permission/provider failures are explicit; internal engine row identities are skipped. page/reportDir adds read-only page query bindings without editing or validating native visuals.
  • Preview critique checks measured SVG text bounds, ellipses, axis rotation, categorical palette size, null/zero series, empty required slots, missing formats, page-background text contrast, legend/plot intersections, pie slice count and dual-axis review, with actionable paths/fixes and explicit coverage limits. It is not analytical correctness, accessibility or host-interaction certification.
  • preview_variants makes one identical data query for up to 4 candidate specs and returns compact results; scoped definitions must match. Prefer it to preview_visual when you don't need the full option JSON, which can be very large.
  • read_visual returns the migrated spec, bindings, pane objects, layout, source-version provenance, etag and live PNG. diff_visual is read-only.
  • update_visual accepts RFC 6902 operations, defaults to dry run, protects identity/prototype/version paths and checks intervening file changes. It preserves field queries for styling-only edits and refuses implicit rebinding. A legacy inline measure with no stored owning-table metadata returns table:null.
  • list_pages reads all visual positions to help avoid overlap. validate_visuals examines only the stable Vilsem Renderer GUID. commit_visual adds one new visual, rejects collisions and updates only missing renderer resources/registration; it does not rebuild or serialize other report content.
  • list_templates output is very large; save it to a file and extract meta.id, meta.description and slots with a script.

Commits always return nextStep: relay it verbatim. First renderer registration requires closing Desktop without saving and reopening the .pbip; later commits and non-dry-run updates require Apply external changes. measureWarning lists visual-scoped measures when present. validate_visuals returns its existing results array as the first text block, now with nativeMeasures on each visual; a second JSON text block contains summary (visualCount, visualsWithNativeMeasures, nativeMeasureCount). Counts cover Vilsem visuals only; no model changes are performed.

Contoso reference examples and data-art recipes are model-specific examples, not list_templates entries. Adapt bindings and calculations to your own schema. Native skill installation copies five skill files; the example JSON files stay in the installed MCP package's docs/examples/contoso/.

Interactions

Rendered Vilsem ECharts visuals cross-filter through Power BI selection IDs, accept cross-highlights, support drill-through/context-menu requests, native tooltips and bookmark selection restoration. Those host contracts have automated harness tests. Availability depends on bound field identities and report configuration; report-page tooltips, drill-through destinations and bookmarks need testing in the actual report. A PNG preview does not verify interactions. DOM-adapter visuals and every template transform have not been certified for interaction parity.

What this does NOT do

  • Create, edit or validate native Power BI visuals.
  • Create pages, slicers, filters, bookmarks or themes (the agent can create pages by editing PBIR; call get_playbook section pbir-pages, or read vilsem://skill/pbir-pages).
  • Change semantic models or model metadata. To persist measures, the agent edits TMDL with the user's agreement or uses Microsoft's Power BI Modeling MCP — see Measures: prototype vs publish.
  • Read or write PBIX files. Existing enhanced PBIR report folders are required.

Headless previews support the core ECharts composition types and declarative templates. DOM-adapter visual types are rejected rather than emitted as empty or substituted charts. Previews render chart marks and option; renderer-owned card chrome/title headers and existing report-level filters are not replayed. Fonts can differ between server PNGs and Desktop. Preview queries and arbitrary DAX default to 200 rows and accept maxRows up to 10,000. Desktop's categorical host reduction is 2,000 rows.

Current report and visual limitations

Local Desktop models only in 0.9. Online models are disabled by default. See the experimental section above.

This table describes MCP 0.9.3 with core 0.8.3 / renderer 4.46. A tool PASS or saved visual.json is not evidence that every report, visual state or Power BI target works.

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!