fabric-dw

fabric-dw

Microsoft Fabric Data Warehouse と SQL Analytics Endpoint 向けの Python CLI および MCP サーバーです。ターミナルまたは AI エージェントから、管理、クエリ、最適化、セキュリティ保護を行えます。

ドキュメント全文：fdw.debruyn.dev

📣 公開しました！ [fabric-dw] の開発背景について、告知ブログ記事をご覧ください。

説明

fabric-dw は、Microsoft Fabric Data Warehouse と SQL Analytics Endpoint を管理するための 2 つのインターフェースを提供します。

• CLI：一般的な DW 管理タスク向けのコマンドラインツールです。
• MCP サーバー：Model Context Protocol サーバーです。AI アシスタント向けに、DW の操作をツールとして公開します。

認証は FABRIC_AUTH 環境変数で設定します。デフォルト（FABRIC_AUTH=default）では、環境変数、Workload／Managed Identity、Azure CLI、Azure Developer CLI、Azure PowerShell、対話型ブラウザーの順に確認する azure-identity DefaultAzureCredential を使用します。これらのいずれかで認証できます。認証チェーン、サポートされているすべてのソース、デバッグのヒントについては、認証ドキュメントをご覧ください。

インストール

pip install fabric-dw
# or run without installing:
uvx fabric-dw --help
# or install persistently on PATH:
uv tool install fabric-dw

インストール後、fdw コマンドは fabric-dw の短縮エイリアスとして使用でき、どちらも同じエントリーポイントを実行します。MCP サーバーのセットアップ、アップグレード、プレリリースビルドについては、インストールドキュメントをご覧ください。

クイックスタート

CLI

ワークスペースは、コマンドグループの前に指定するグローバルなルートオプション -w ／ --workspace です。fdw config set workspace <NAME> で一度デフォルトを設定すれば、以降の呼び出しでは -w を省略できます。ワークスペースの解決順序：(1) -w フラグ、(2) FABRIC_DW_DEFAULT_WORKSPACE 環境変数、(3) 設定済みのデフォルト。

# 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 [email protected] --object dbo.orders

# Deny access to sensitive columns (column-level security)
fdw permissions cls deny SalesWH SELECT --to [email protected] \
    --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 サーバー

MCP クライアントの設定（例：Claude Desktop、VS Code）に追加します。

{
  "mcpServers": {
    "fabric-dw": {
      "command": "uvx",
      "args": ["--from", "fabric-dw", "fabric-dw-mcp"]
    }
  }
}

MCP サーバーは、すべての CLI 操作（workspaces、warehouses、SQL endpoints、schemas、tables、views、queries、snapshots、restore points、audit、statistics、permissions、sql-pools）を MCP ツールとして公開します。詳細な AI 支援分析のため、Claude Code エージェントスキル（query-optimizer、warehouse-performance、dbt-setup）も同梱されています。デフォルト以外の認証モードが必要な場合は、環境に FABRIC_AUTH を設定してください。

Claude Code と GitHub Copilot CLI のどちらでも、fabric-dw プラグインマーケットプレイスから 1 つのコマンドでスキルと MCP サーバーの両方をインストールできます。/plugin marketplace add sdebruyn/fabric-dw-mcp-cli を実行し、続けて /plugin install fabric-dw@fabric-dw を実行してください。詳細は、エージェントスキルドキュメントをご覧ください。

Docker で実行する

Docker イメージのデフォルトの ENTRYPOINT は MCP サーバー（fabric-dw-mcp）です。そのまま MCP クライアントで使用するか、エントリーポイントを上書きして CLI を実行してください。

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

開発用イメージ（main へのマージごとにビルド）：ghcr.io/sdebruyn/fabric-dw:main または :<version>.dev<N>。

パッケージページ：ghcr.io/sdebruyn/fabric-dw

セキュリティ環境変数

変数	デフォルト	説明
FABRIC_MCP_READONLY	未設定	1 に設定すると、execute_sql を SELECT/WITH に制限し、すべての変更ツールをブロックします。
FABRIC_MCP_ALLOW_DESTRUCTIVE	未設定	1 に設定すると、恒久的に破壊的なツール（delete_*、clear_table、restore_warehouse_in_place）を有効にします。デフォルトでは無効です。
FABRIC_MCP_WORKSPACES	未設定	サーバーがアクセスできるワークスペース名または GUID をカンマ区切りで指定します。未設定の場合、すべてのワークスペースが許可されます。
FABRIC_MCP_ALLOW_REMOTE	未設定	1 に設定すると、HTTP トランスポート（--transport http）をループバック以外のアドレスにバインドできます。警告がログに記録されます。エンドポイントの前段に TLS 対応の認証付きリバースプロキシを配置し、Host の検証を有効なままにするために --allowed-host を指定してください。MCP サーバーのホスティングを参照してください。

HTTP トランスポート

MCP サーバーは、リモートクライアント向けに HTTP モードで起動できます。

fabric-dw-mcp --transport http [--host 127.0.0.1] [--port 8000]

デフォルトではループバックにバインドされ、Host と Origin の検証は自動的に処理されます。それ以外の場所にバインドするには、FABRIC_MCP_ALLOW_REMOTE=1 と --allowed-host が必要です。また、エンドポイントには認証機能も TLS も組み込まれていないため、必ず認証付きリバースプロキシを前段に配置してください。その設定については、MCP サーバーのホスティングを参照してください。

コンテナーで開発する

リポジトリを GitHub Codespaces または VS Code の Remote-Containers 拡張機能で開きます。devcontainer には Python 3.14、uv、Azure CLI、GitHub CLI があらかじめインストールされています。

貢献

開発環境のセットアップ、ブランチの運用方法、ローカルでのテスト実行方法については、CONTRIBUTING.mdを参照してください。

📖 ドキュメント：fdw.debruyn.dev（またはローカルで uv run --only-group docs zensical serve を実行してください）。

セキュリティ

脆弱性は非公開で報告してください。SECURITY.mdを参照してください。

行動規範

このプロジェクトはContributor Covenant 2.1に従っています。

ライセンス

MIT。Copyright (c) 2026 Sam Debruyn