想定読者
- 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 回にわたり扱います。