This release is a pre-release and may not be stable for production use.
fabric-dw
Python CLI and MCP server for Microsoft Fabric Data Warehouses and SQL Analytics Endpoints: administer, query, optimize, and secure them from your terminal or your AI agent.
Full documentation: fdw.debruyn.dev
📣 Just announced! Read the story behind fabric-dw in the announcement blog post.
Description
fabric-dw provides two interfaces for managing Microsoft Fabric Data Warehouses and SQL Analytics Endpoints:
- CLI: a command-line tool for common DW administration tasks.
- MCP server: a Model Context Protocol server that exposes DW operations as tools for AI assistants.
Authentication is configured via the FABRIC_AUTH environment variable. The default (FABRIC_AUTH=default) uses azure-identity DefaultAzureCredential, which walks environment variables, Workload/Managed Identity, Azure CLI, Azure Developer CLI, Azure PowerShell, and interactive browser in order. Any of these will satisfy it. See the Authentication docs for the full chain, all supported sources, and debugging tips.
Installation
pip install fabric-dw
# or run without installing:
uvx fabric-dw --help
# or install persistently on PATH:
uv tool install fabric-dw
After installation, the fdw command is a short alias for fabric-dw; both invoke the same entry point. See the Install docs for MCP server setup, upgrading, and prerelease builds.
Quick Start
CLI
The workspace is a global root option -w / --workspace placed before the command group. Set a default once with fdw config set workspace <NAME> and omit -w on every subsequent call. Workspace resolution order: (1) -w flag, (2) FABRIC_DW_DEFAULT_WORKSPACE env var, (3) configured default.
# Run without installing; install to get the fdw alias
uvx fabric-dw --help
# Set a default workspace once; all subsequent commands pick it up
fdw config set workspace SalesWS
# -- Run and explain SQL --
# Execute a query against a warehouse
fdw sql exec SalesWH -q "SELECT TOP 10 * FROM dbo.orders ORDER BY order_date DESC"
# Capture an estimated execution plan as SVG -- no SSMS or Windows needed
fdw sql plan SalesWH -f query.sql --format svg -o plan.svg
# -- Performance mission-control --
# See what is running right now
fdw queries running SalesWH
# Long-running queries from the past hour
fdw queries long-running SalesWH --ago 1h
# Kill a runaway session by ID
fdw queries kill SalesWH 55
# Most-repeated queries over the past 24 hours
fdw queries frequent SalesWH --ago 24h
# -- Optimize --
# Inspect a statistics histogram with inline terminal bar charts
fdw statistics show SalesWH dbo.orders st_order_date --histogram
# Re-cluster a table on a new key (transactional CTAS-swap, auto-rollback on failure)
fdw tables cluster-by SalesWH dbo.orders --cluster-by customer_id
# -- Time travel + export --
# Browse the table as it looked 2 hours ago
fdw tables read SalesWH dbo.orders --ago 2h
# Export a point-in-time snapshot to Parquet
fdw tables export SalesWH dbo.orders --output snapshot.parquet --ago 2h
# -- Governance --
# Grant SELECT on a specific table
fdw permissions sql grant SalesWH SELECT --to analyst@company.com --object dbo.orders
# Deny access to sensitive columns (column-level security)
fdw permissions cls deny SalesWH SELECT --to contractor@company.com \
--object dbo.orders --columns salary,bonus
# Create a row-level security policy (filter rows by SalesRep)
fdw permissions rls create SalesWH rls.SalesFilter \
--filter "rls.fn_sales_filter(SalesRep)" --on dbo.orders
# -- Load + scaffold --
# Load a local Parquet file and auto-create the table from its schema
fdw tables load SalesWH dbo.orders --file orders.parquet --create
# Scaffold a full dbt-fabric project wired to the warehouse
fdw dbt init SalesWH ./my-dbt-project --project-name sales_dw --with-sources
MCP Server
Add to your MCP client configuration (e.g. Claude Desktop, VS Code):
{
"mcpServers": {
"fabric-dw": {
"command": "uvx",
"args": ["--from", "fabric-dw", "fabric-dw-mcp"]
}
}
}
The MCP server exposes all CLI operations as MCP tools (workspaces, warehouses, SQL endpoints, schemas, tables, views, queries, snapshots, restore points, audit, statistics, permissions, sql-pools). Bundled Claude Code agent skills (query-optimizer, warehouse-performance, dbt-setup) are included for deeper AI-assisted analysis. Set FABRIC_AUTH in the environment if you need a non-default auth mode.
Both the skills and the MCP server install in one command via the fabric-dw plugin marketplace, for Claude Code and GitHub Copilot CLI alike: /plugin marketplace add sdebruyn/fabric-dw-mcp-cli then /plugin install fabric-dw@fabric-dw. See the Agent Skills docs for details.
Run in Docker
The Docker image's default ENTRYPOINT is the MCP server (fabric-dw-mcp). Use it as-is with your MCP client, or override the entrypoint to run the CLI instead.
docker pull ghcr.io/sdebruyn/fabric-dw:latest
# Run the MCP server (default entrypoint, connect via stdio from your MCP client):
docker run --rm -i \
-e AZURE_CLIENT_ID=… \
-e AZURE_TENANT_ID=… \
-e AZURE_CLIENT_SECRET=… \
-e FABRIC_AUTH=sp \
ghcr.io/sdebruyn/fabric-dw
# Run the CLI instead (override the entrypoint):
docker run --rm \
--entrypoint fabric-dw \
-e AZURE_CLIENT_ID=… \
-e AZURE_TENANT_ID=… \
-e AZURE_CLIENT_SECRET=… \
-e FABRIC_AUTH=sp \
ghcr.io/sdebruyn/fabric-dw --help
Dev images (built from every main merge): ghcr.io/sdebruyn/fabric-dw:main or :<version>.dev<N>.
Package page: ghcr.io/sdebruyn/fabric-dw
Security environment variables
| Variable | Default | Description |
|---|---|---|
FABRIC_MCP_READONLY |
unset | Set to 1 to restrict execute_sql to SELECT/WITH and block all mutating tools. |
FABRIC_MCP_ALLOW_DESTRUCTIVE |
unset | Set to 1 to enable permanently-destructive tools (delete_*, clear_table, restore_warehouse_in_place). Disabled by default. |
FABRIC_MCP_WORKSPACES |
unset | Comma-separated workspace names or GUIDs the server may touch. Unset = all workspaces allowed. |
FABRIC_MCP_ALLOW_REMOTE |
unset | Set to 1 to allow the HTTP transport (--transport http) to bind on a non-loopback address. A warning is logged; ensure an authenticating reverse proxy with TLS fronts the endpoint, and pass --allowed-host so Host validation stays on. See Hosting the MCP server. |
HTTP transport
The MCP server can be started in HTTP mode for remote clients:
fabric-dw-mcp --transport http [--host 127.0.0.1] [--port 8000]
It binds to loopback by default, where Host and Origin validation is handled for you. Binding anywhere else requires FABRIC_MCP_ALLOW_REMOTE=1 and --allowed-host, and the endpoint has no built-in authentication or TLS, so always front it with an authenticating reverse proxy. See Hosting the MCP server for that setup.
Request bodies are capped at 4 MiB; anything larger is rejected with HTTP 413. In practice only a multi-megabyte execute_sql script or object definition can reach that. The stdio transport has no such limit.
Protocol versions
The server speaks MCP revision 2026-07-28 and continues to serve 2025-11-25 clients from the same process, so no client change is needed. Two protocol-level notes for anyone driving the server directly.
ping was removed in revision 2026-07-28, but only for clients that negotiate that revision: a 2025-11-25 client can still call it and this server still answers. A 2026-07-28 client gets -32601 instead. Note that the SDK's own client emits a deprecation warning from send_ping() in both cases, so the warning alone does not tell you whether the call worked.
Unknown methods return -32601 (method not found) under both revisions.
Develop in a container
Open the repo in GitHub Codespaces or VS Code's Remote-Containers extension. The devcontainer pre-installs Python 3.14, uv, Azure CLI, and the GitHub CLI.
Contributing
See CONTRIBUTING.md for dev setup, branch flow, and how to run tests locally.
📖 Docs: fdw.debruyn.dev (or run uv run --only-group docs zensical serve locally).
Telemetry
fabric-dw collects opt-out usage telemetry. No SQL statements or credentials are ever sent. To opt out, set FABRIC_DW_TELEMETRY_OPT_OUT=1. See the Telemetry docs for the full list of collected fields and all opt-out methods.
Security
Please report vulnerabilities privately. See SECURITY.md.
Code of Conduct
This project follows the Contributor Covenant 2.1.
License
MIT. Copyright (c) 2026 Sam Debruyn
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file fabric_dw-2026.7.4.dev22.tar.gz.
File metadata
- Download URL: fabric_dw-2026.7.4.dev22.tar.gz
- Upload date:
- Size: 1.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
320fcf569b96add2ac05cffbd8d6857201bee73d3080c46a904122934f5dfa76
|
|
| MD5 |
d6748558b617c03748688b1c02b4745a
|
|
| BLAKE2b-256 |
89cab1db89d15c01d975190fdb8fe0d7bcf11ef9fcafa1f4b737984698677663
|
File details
Details for the file fabric_dw-2026.7.4.dev22-py3-none-any.whl.
File metadata
- Download URL: fabric_dw-2026.7.4.dev22-py3-none-any.whl
- Upload date:
- Size: 582.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fca1d8351b0e3a96d336959cebc38b8c772ba98ba930aa9f2fa312634d26bccc
|
|
| MD5 |
d7105074f2b97fa97f4a96f79bbd3420
|
|
| BLAKE2b-256 |
41cf4dd5796393350a44a007cf1d8e2660a7cfad1b037ad6af7c9eeeedf4fc8a
|
