fabric-mcp-server

Microsoft Fabric as an MCP server and as a CLI, from one tool registry.

• The MCP server gives Claude Code, Claude Desktop, or any Model Context Protocol client typed, permission-gated access to Fabric.

• The fabric CLI exposes the exact same tools from a shell, so you can pipe large results through jq or PowerShell, loop over workspaces in one call, and run unattended from a scheduled task with no model in the loop.

Both talk to the public Fabric REST API (api.fabric.microsoft.com), the Power BI REST API (api.powerbi.com), and the OneLake DFS endpoint, authenticating with @azure/identity.

Features

• Resolve workspaces, items, pipelines, deployment pipelines, folders, and semantic models by display name or GUID.

• Continuation-token paging, HTTP 429 retry (honors Retry-After), and long-running-operation polling built in.

• Read-only by default. Every mutating tool is gated behind FABRIC_MCP_MODE=write on both surfaces and audit-logged to stderr.

• Safety rails on the dangerous operations: deploy_stage and commit_to_git refuse blanket "everything" runs; update_item_definition and delete_item snapshot the live definition first for one-call rollback.

Related MCP server: PowerBI MCP Server

Which surface when

Tools

Tool names and parameters are identical on both surfaces. On the CLI, list_item_runs is fabric list-item-runs (either spelling works) and each parameter is a --flag.

Requirements

• Node.js >= 20

• An Entra identity with access to the target workspaces.

• For execute_dax: Build permission on the semantic model and the tenant's "Dataset Execute Queries REST API" setting enabled.

• For bind_semantic_model_connection: the caller must own the model (takeover_item first if not).

Install

git clone <this-repo-url> fabric-mcp-server
cd fabric-mcp-server
npm install
npm link        # optional: puts `fabric` and `fabric-mcp-server` on your PATH

Configuration

All configuration is via environment variables (see .env.example). Both surfaces read the same variables.

Auth modes

• interactive — opens a browser; best for desktop/AVD. With the persistent cache, the CLI signs in once and then runs silently.

• device-code — prints a code + URL to stderr; for SSH / WSL / headless.

• cli — reuses your az login session.

• azure-powershell — reuses your Connect-AzAccount session.

• service-principal — non-interactive; the right choice for scheduled tasks.

• managed-identity — for hosting on Azure.

• default — tries env → managed identity → CLI → browser in turn.

Use as an MCP server

Add to your MCP client config (~/.claude.json for Claude Code, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "fabric": {
      "command": "node",
      "args": ["/absolute/path/to/fabric-mcp-server/index.js"],
      "env": {
        "FABRIC_AUTH_MODE": "interactive",
        "AZURE_TENANT_ID": "<your-entra-tenant-id>"
      }
    }
  }
}

Add "FABRIC_MCP_MODE": "write" to the env block to expose the write tools. Existing v1.x client configs keep working unchanged.

Use as a CLI

fabric tools                                  # every tool with its mode
fabric help list-item-runs                    # a tool's flags
fabric list-workspaces
fabric list-item-runs --workspace BI-Prod --item brz_nb_clean --status Failed --top 5
fabric get-item-definition --workspace BI-Prod --item "Sales Model" --out sales-model.json

Conventions:

• Flags mirror tool parameters; --job_instance_id and --job-instance-id are equivalent.

• Object and array parameters take inline JSON or @path/to/file.json. String arrays also take comma-separated values: --items "Notebook A,Notebook B".

• Booleans: --wait, --wait=false, --no-wait.

• Output is JSON on stdout. --compact for one line, --out <file> to write to disk and print a short receipt instead.

• Exit codes: 0 success, 1 the tool failed (message on stderr), 2 usage problem.

• Write tools need FABRIC_MCP_MODE=write in the environment. The CLI will not accept it as a flag, so the same safety property holds on both surfaces.

Filtering large results in the shell

The point of the CLI is that filtering happens before anything reaches a model or your eyes.

# Which tables in the lakehouse have not been written today?
fabric list-onelake --workspace BI-Prod --item Bronze --directory Tables/dbo |
  ConvertFrom-Json | Select-Object -Expand paths |
  Where-Object { [datetime]$_.lastModified -lt (Get-Date).Date } |
  Select-Object name, lastModified

# Failed runs across every pipeline in a workspace, last 24 hours
fabric list-pipelines --workspace BI-Prod | jq -r '.pipelines[].displayName' | while read -r p; do
  fabric list-pipeline-runs --workspace BI-Prod --pipeline "$p" --status Failed --top 5 --compact |
    jq -c --arg p "$p" '.runs[] | select(.startTimeUtc > (now - 86400 | todate)) | {pipeline: $p, startTimeUtc, failureReason}'
done

Scheduled tasks

Use service-principal auth (or seed the persistent cache with one interactive sign-in under the task's account) and FABRIC_MCP_MODE=write only when the task needs it.

# Morning health check written to a share, no model involved
$env:FABRIC_AUTH_MODE = "service-principal"
fabric list-pipeline-runs --workspace BI-Prod --pipeline Nightly-Load --status Failed --top 3 --compact |
  Set-Content "\\share\reports\fabric-health-$(Get-Date -f yyyyMMdd).json"

Deployment recipes the new tools cover

Semantic model promoted through a deployment pipeline will not refresh. Every leg resets its connections to Automatic.

get_item_connections   (target model)  -> confirm paths point at the target stage, unboundCount > 0
bind_semantic_model_connection copy_from=<a bound model in the same workspace>
refresh_dataset

Git-synced model fails with "default data connection without explicit credentials".

get_dataset_datasources (a working sibling) -> gatewayId + datasourceId values
bind_dataset_to_gateway  gateway_id=... datasource_ids=[...]

Notebook just wrote to a lakehouse but the SQL endpoint still shows the old schema.

refresh_sql_endpoint_metadata --workspace W --item Lakehouse --tables dbo.lp_waterusage

Commit one item from a workspace with other people's dirty items.

get_git_status   -> see what is dirty
commit_to_git    items=["my_notebook"] comment="..."   (Selective; nothing else moves)

Development

npm test          # node --test: registry, CLI arg mapping, helpers, polling

Tools live in src/tools/*.js as plain { name, description, mode, schema, handler } objects. src/mcp/register.js wraps them for MCP; src/cli/main.js maps each schema field to a flag. Adding a tool means adding one object; both surfaces pick it up.

Security notes

• No secrets are stored in the repo. Credentials come from environment variables at runtime; .env is git-ignored.

• Write tools are only registered (MCP) or runnable (CLI) under FABRIC_MCP_MODE=write, and each logs an [AUDIT] line to stderr.

• The persistent token cache uses the OS secure store via @azure/identity-cache-persistence. If the native module is unavailable the process falls back to the in-memory cache and says so on stderr.

• list_onelake / read_onelake_file use the Azure Storage token audience; the same credential acquires it.

• execute_dax uses the Power BI executeQueries API, which only runs read-only DAX.

License

MIT