想定読者

Microsoft Fabric を AI エージェント（Claude Code 等）で操作したいデータエンジニア・BI エンジニア

MCP（Model Context Protocol）サーバーを Claude Code に追加するときの実用ノウハウを探している方

TL;DR

Microsoft Fabric を AI エージェントから操作するための MCP サーバーは現状 2 つ あり、役割が補完関係になっています。

MCP サーバー	担当領域	主な用途
Fabric MCP Server（Microsoft 公式・`@microsoft/fabric-mcp`）	データ層（OneLake / Lakehouse / Notebook / アイテム管理 / REST API 参照）	テーブル一覧・ファイル操作・REST API ベストプラクティス取得
Power BI Modeling MCP Server（Microsoft 公式・VS Code 拡張）	セマンティックモデル層（列・メジャー・リレーション・DAX）	Semantic Model の構築・列名一括リネーム・DAX 検証・ライブデプロイ

ただし両者は 配布形態が異なるため、Claude Code への追加方法も別ルートになります。一律「VS Code 拡張で OK」とすると Fabric MCP の方は接続できません。

本記事では、両 MCP の 役割整理 + 配布形態の違い + セットアップ詰まり所 + 実証ケース 2 つ + 落とし穴集を、約 1 か月の実運用ベースで共有します。

1. 第 1 回からの接続

前回の記事（第 1 回・土台編）では、情シス部長が 1 人で Power BI モノリスから Microsoft Fabric への移行を進めている開発スタック全体を紹介しました。その中核に位置するのが Claude Code 拡張から呼び出す 5 ツール:

Fabric MCP Server
Power BI Modeling MCP Server
Fabric CLI
Azure CLI
git CLI

このうち、MCP の 2 つを深掘りするのが本記事です。CLI 3 つの使い分けは別記事に分けます。

2. 2 つの MCP Server の役割整理

2.1 補完関係（カバー範囲の図）

各 MCP の代表的なツール一覧は次節 2.2 の早見表にまとめています。

2.2 どちらをいつ使うか

やりたいこと	使う MCP
Lakehouse のテーブル一覧を取得・スキーマ確認	Fabric MCP（`onelake_table_list` / `onelake_table_get`）
Notebook を import / run	Fabric CLI（MCP ではない）
OneLake Files にファイルを読み書き	Fabric MCP（`onelake_upload_file` / `onelake_file_list`）
Fabric REST API のスキーマを知りたい	Fabric MCP（`publicapis_get`）
セマンティックモデルに列を追加 / リネーム	PBI Modeling MCP（`column_operations`）
DAX メジャーを作成・編集・バッチ更新	PBI Modeling MCP（`measure_operations`）
DAX クエリの結果を取得して値を検証	PBI Modeling MCP（`dax_query_operations.Execute`）
Direct Lake テーブル追加 + Refresh Full	PBI Modeling MCP（`table_operations` + `model_operations`）

「Lakehouse 側のことは Fabric MCP / Semantic Model 側のことは PBI Modeling MCP」と覚えるのが早いです。

3. 配布形態が 3 パターン違うという発見

ここが本記事で一番伝えたい部分です。

MCP サーバーには配布形態の異なる 3 つのパターンがあり、Claude Code への追加方法もそれぞれ変わります。「VS Code 拡張専用なので Claude Code からは使えない」と安易に判断すると見落とします。

3.1 3 パターンの分類

パターン	配布形態	例	Claude Code への追加
A: npm パッケージ直接型	公式 npm（または PyPI）パッケージあり。VS Code 拡張は同じパッケージを内部起動するラッパー	Azure MCP Server	`npx -y <package>` を `command` に指定
B: 拡張バイナリ共有型	VS Code 拡張に同梱された `.exe` を VS Code ランタイム外でも起動可能	Power BI Modeling MCP	`.vscode/extensions/<拡張>/server/*.exe` を直接 command 指定
C: 拡張ランタイム依存型	VS Code 拡張同梱の `.exe` は VS Code 外で初期化応答せず・npm 版が別途必要	Fabric MCP	`npm install -g` でグローバルインストール後、`fabmcp` を command 指定

3.2 パターン判別フロー

実体確認は数十秒で済みます。「○○ は VS Code 拡張専用」と断定する前に、上記フローを必ず通すと事故が減ります。

3.3 本記事の 2 MCP がどのパターンか

MCP	パターン
Fabric MCP Server	C: 拡張ランタイム依存型 — VS Code 拡張版の `server/fabmcp.exe` は VS Code 外で initialize 無応答。Claude Code 用には npm グローバルインストールが別途必須
Power BI Modeling MCP	B: 拡張バイナリ共有型 — VS Code 拡張をインストールすると `.exe` が配置され、Claude Code から直接そのパスを指定して起動可能

つまり「Fabric は npm」「PBI Modeling は拡張同梱 .exe」と 配布ルートが違う。これが本記事の核心です。

4. セットアップで詰まりやすい所

4.1 Fabric MCP — beta バージョン罠

@microsoft/fabric-mcp には過去に beta.10 で fabmcp.exe が起動時にハングするバグがあり、beta.9 にダウングレードすると復旧する状態でした。

# beta.10 でハングする場合
npm install -g @microsoft/fabric-mcp@0.0.0-beta.9

注（2026 年 4 月リリース 1.0.0 について）: その後 VS Code 拡張版として Microsoft Fabric MCP Server の 1.0.0（pre-release）が 2026 年 4 月にリリースされており、ここで挙げた起動ハング問題が 解消されている可能性があります。本記事の検証は npm 配布の beta 系列（beta.9 / beta.10）時点のものなので、最新版で再現する場合は不要な可能性がある旨をご了承ください（実機検証は未実施）。なお、本記事の他章で述べた「拡張版バイナリは VS Code ランタイム外で initialize 無応答」の特性も最新版で変わった可能性があります。検証次第追記します。

`.mcp.json` 例（プロジェクトルート）

{
  "mcpServers": {
    "fabric-mcp-server": {
      "command": "cmd",
      "args": ["/c", "fabmcp", "server", "start", "--mode", "all"]
    }
  }
}

Windows では npx を直接 command に指定すると /doctor で警告が出るため、cmd /c ラッパーを介して fabmcp を呼ぶ形が安定です。

4.2 PBI Modeling MCP — 3 つの設定罠

(1) `PBI_MODELING_MCP_ACCESS_TOKEN` 環境変数の罠

公式ドキュメントには出てこないが、この環境変数を設定すると対話型認証がブロックされ「Authentication failed for all authenticators」エラーになります。

{
  "mcpServers": {
    "powerbi-modeling-mcp": {
      "command": "C:\\Users\\<user>\\.vscode\\extensions\\analysis-services.powerbi-modeling-mcp-0.4.0-win32-x64\\server\\powerbi-modeling-mcp.exe",
      "args": ["--start", "--skip-confirmation"],
      "env": {}
    }
  }
}

ポイント: env は空オブジェクト。トークンは MCP サーバー自体の認証用途で、XMLA/ADOMD 接続には使われないので不要です。空にすると ConnectFabric 時にブラウザ対話型認証へフォールバックして成功します。

(2) Fabric 管理ポータルの設定

Fabric 管理ポータルで「Power BI MCP サーバーエンドポイント（プレビュー）」を有効化する必要があります（テナント管理者権限が必要）。これを忘れると ConnectFabric 時に接続失敗します。

(3) ConnectFabric のワークスペース名

workspaceName は Fabric ポータルの表示名と 完全一致が必要。空白や大文字小文字の差で接続失敗します。

# 動作例（Claude Code から呼び出し）
mcp__powerbi-modeling-mcp__connection_operations:
  operation: ConnectFabric
  workspaceName: <ワークスペース表示名>
  semanticModelName: <Semantic Model 表示名>

4.3 `.mcp.json` 編集は Hot Reload される

.mcp.json を編集して MCP サーバーを追加・変更しても、Claude Code は同一セッション内で hot reload します。「保険として再起動」は不要です。

実証: Azure MCP を追加した直後、その場で mcp__azure__subscription_list を呼べた、というケースで確認しています。

5. 実践ケース 1: 列名辞書テーブル起点の Semantic Model 列名日本語化

両 MCP を組み合わせると データ層〜 Semantic Model 層の一気通貫オペレーションが AI エージェント内で完結します。最初の実例として、メダリオンアーキテクチャの全層にまたがる「列名日本語化」を紹介します。

5.1 ねらい

セマンティックモデルの列名は 日本語表示 が望ましい。理由は単純で、エンドユーザーが Power BI Desktop でフィールド名から意味を即座に理解できる + Copilot や DA（データエージェント）が正しい列を選びやすくなるからです。

ただし物理列名は英語（snake_case）で持ちたい。Spark や SQL の取り回しやすさのためです。

つまり 「物理は英語、表示は日本語」を両立したい。

5.2 全体フロー

補足: ここで言う「列名 mapping テーブル」「列名辞書テーブル」は、メダリオンアーキテクチャの Bronze 層に自前で持つメタデータテーブルです。物理的な命名は任意で、筆者の環境では bronze.column_mapping / bronze.data_dictionary として運用しています。

5.3 各 MCP の役割分担

ステップ	使うツール	内容
(1) 物理層の確認	Fabric MCP（`onelake_table_get`）	Silver / Gold テーブルのスキーマ取得
(2) 列名辞書取得	Fabric MCP（`onelake_table_get`）or 直接 SQL	列名辞書テーブルから英→日 mapping を読み込む
(3) Semantic Model に live 接続	PBI Modeling MCP（`ConnectFabric`）	対象 Semantic Model にライブ接続
(4) 列名バッチ Rename	PBI Modeling MCP（`column_operations` Rename）	数十列を一括日本語化
(5) DAX メジャーの追随	PBI Modeling MCP（`measure_operations` Update）	列参照のあるメジャーを書き換え
(6) ライブデプロイ	PBI Modeling MCP（`database_operations` DeployToFabric）	`push_measures.py` 等のローカル script 不要

5.4 ConnectFabric ライブ接続の威力

ConnectFabric（XMLA 経由のライブ接続）で繋いだ後の column_operations.Rename は、Semantic Model 内の DAX メジャーが自動的に新列名へ追随します。

これがオフライン接続（ConnectFolder で TMDL を編集）との大きな差です。オフラインだと別途 measure_operations.Update でメジャーの DAX を書き換える必要があります。

実績規模（筆者の環境で運用中の 3 つの Semantic Model）:

Semantic Model	列数	DAX 追随	所要時間
Semantic Model 1	69 列	13 本自動追随	Rename バッチ数秒
Semantic Model 2	150 列	26 本自動追随	同上
Semantic Model 3	49 列	当初 ConnectFolder で実施したため別途 Update が必要だった	バッチ数秒 + DAX 書き換え

合計 268 列 + 数十本の DAX が AI エージェント駆動で日本語化されました。

5.5 落とし穴: `.pbip` レポートの visual.json は追随しない

Rename が自動追随するのは Semantic Model 内の DAX のみ。Power BI Desktop で作る .pbip レポートの visual.json 内で参照している列名（Entity / Property）は 手動更新が必要です。

これは Python の単純な一括置換で対応できます:

content = content.replace('contract_sales', 'contract_sales_amount')

6. 実践ケース 2: Direct Lake 新規テーブル追加から Refresh Full まで

次は Lakehouse 側で新規 Gold テーブルを作って Semantic Model に Direct Lake で公開する ケース。これも 2 MCP の連携で完結します。

6.1 標準フロー（5 ステップ）

6.2 Refresh Full が必須な理由

Direct Lake モードの場合、テーブル追加だけでは 列メタデータとリレーションが再計算されません。refreshType=Automatic だと Power BI Desktop で「リレーションシップは再計算する必要がある」エラーが出ます。

refreshType=Full を明示することで、列メタデータとリレーションが一括再構築されます。

6.3 制約: `IsKey` / `IsUnique` / `IsNullable` は指定不可

Direct Lake テーブルでは列に isKey: true / isUnique: true / isNullable: false を指定すると次のエラーで失敗します:

IsKey is only supported for DirectQuery tables

これは仕様で、Direct Lake では エンジンが RowNumber 列で自動管理するためです。主キーの一意性保証は 上流（Lakehouse 側）の責務になります。

6.4 物理差し替え時の落とし穴: Direct Lake は古い Parquet を見続ける

Lakehouse 側で overwriteSchema=true でテーブルを物理差し替えしたとき、Semantic Model 側は 古い Parquet を参照したままキャッシュされることがあります。Power BI レポートに古いデータが出続ける現象です。

# 解消手順
mcp__powerbi-modeling-mcp__model_operations:
  operation: Refresh
  refreshType: Full

Refresh Full で物理参照が更新されます。

なお fab api -X post /workspaces/.../semanticModels/.../refreshes は本記事執筆時点で 404 EntityNotFound を返すため、Semantic Model Refresh は PBI Modeling MCP 経由が確実です。

7. ハマったところ・落とし穴まとめ

実運用で踏んだ落とし穴を一覧化します。

7.1 認証・接続系

症状	原因	対処
ConnectFabric で「Authentication failed for all authenticators」	`PBI_MODELING_MCP_ACCESS_TOKEN` env が設定されている	env から削除（`"env": {}`）
ConnectFabric でワークスペースが見つからない	`workspaceName` の大文字小文字 / 半角全角ズレ	Fabric ポータルの表示名と完全一致させる
MCP サーバー側で `Failed to connect`（30 秒タイムアウト）	`npx` のダウンロード時間が長くタイムアウト超過	`npm install -g` でグローバルインストール

7.2 Semantic Model 側オペレーション

症状	原因	対処
`'A' と 'B' の間にあいまいなパス` で commit が rollback	新リレーション追加前に古いものが残っている	削除 → 追加の順で実行
Direct Lake テーブル Create で `IsKey is only supported for DirectQuery`	Direct Lake で `isKey: true` 指定不可	これらのフラグを指定しない
Lakehouse に列追加したのに Semantic Model に出ない	Semantic Model 側は既存スナップショットのまま	Semantic Model 側で `column_operations Create` で明示追加
measure を別テーブルに移したが DAX 内のテーブル参照が古い	`Move` は DAX を書き換えない	`Update` で DAX 書き換え → `Move` の 2 段階
Power BI 概要ページで同じメジャーが重複表示される	概要ページの表示キャッシュバグ	List / Web モデリング / Desktop で重複なければ実害なし

7.3 ファイル・レポート側

症状	原因	対処
`.pbip` レポートが列名 Rename に追随しない	Rename は Semantic Model 内 DAX のみ自動追随	Python で `visual.json` を一括置換
`measure_operations ExportTMDL` で複数指定しても最初の 1 件しか返ってこない	API 仕様（複数指定は警告のみ）	Claude Code の並列呼び出しで複数同時取得
`measure_operations List` が 200 件で切れる	デフォルト `maxResults: 200`	`filter.maxResults: 500` を指定

7.4 環境構築系

症状	原因	対処
`fabmcp.exe` がハングして MCP 初期化されない	`@microsoft/fabric-mcp@beta.10` のバグ	`npm install -g @microsoft/fabric-mcp@0.0.0-beta.9`（※ 2026 年 4 月リリースの 1.0.0 pre-release で解消されている可能性あり・本記事は beta 系列時点の検証）
ConnectFabric が「サーバーエンドポイントが見つかりません」	管理ポータルでプレビュー機能未有効化	「Power BI MCP サーバーエンドポイント（プレビュー）」を有効化
`.mcp.json` 変更後の反映で迷う	Hot reload を知らない	同一セッションで自動反映・再起動不要

8. まとめ + 連載次回予告

8.1 振り返り

Fabric を AI エージェントで動かす MCP は 2 つあり、補完関係。データ層は Fabric MCP、Semantic Model 層は PBI Modeling MCP。
配布形態は 3 パターンあり、Fabric MCP は npm 版必須・PBI Modeling MCP は拡張バイナリ共有。一律「拡張で OK」と断定しないこと。
セットアップ詰まり所は 環境変数 / プレビュー機能有効化 / バージョン罠の 3 系統。
2 MCP を組み合わせると データ層〜 Semantic Model 層の一気通貫オペレーションが Claude Code 内で完結する。
落とし穴は事前に知っていれば回避可能なものが大半。

8.2 連載次回予告

次回（第 3 回）は Power BI レポートを AI に作らせる — .pbip を使ったビジュアルページの自動生成 を予定しています。Semantic Model の日本語化が「AI に列を選ばせる」前提だったのに対し、第 3 回は「AI にレポートページ自体を組ませる」アプローチです。

第 4 回は Power BI レポートとデータ基盤を Git で管理する — Fabric ワークスペースの履歴管理・コードレビュー実践。第 5 回は Fabric の Git 連携をボタン操作なしで完全自動化する — CLI からのデプロイフロー の 2 本立てで、Fabric の Git 統合周辺を 2 回にわたり扱います。

関連リンク