PowerBI MCP Server

PowerBI MCP サーバー

PowerBI REST API を操作するためのツールを提供する、Model Context Protocol（MCP）サーバーです。このサーバーを使うと、Claude などの AI アシスタントが PowerBI ワークスペースやデータセットを検索し、DAX クエリを実行できます。

警告

セキュリティのベストプラクティス

• 認証情報をバージョン管理にコミットしないでください
• 認証情報は .env ファイルに保存してください（.gitignore に追加してください）
• Azure AD のクライアントシークレットは定期的にローテーションしてください
• 最小権限でアクセスしてください（必要なワークスペース権限のみを付与してください）
• このサーバーは PowerBI データセットへの読み取り／書き込みアクセス権を持つため、注意して使用してください

✨ 特長

• データのクエリ：会話を通じて DAX クエリを実行し、PowerBI データから直接インサイトを抽出、分析できます
• ワークスペースとデータセットの検出：組織の PowerBI 環境で利用可能なデータを確認できます
• データモデルの理解：テーブル、列、リレーションシップの詳細なスキーマ情報を取得できます
• 自然言語からインサイトを取得：PowerBI を開かずにデータについて質問し、回答を得られます

以下の利用可能なツールをご覧ください。

💡 できること

シナリオ	プロンプトの例
利用可能なデータの確認	「アクセスできるワークスペースを教えてください」
レポートの検出	「自分のワークスペースで利用できるレポートは何ですか？」
データスキーマの把握	「データセット [dataset-name] のスキーマを表示してください」
データ更新の確認	「このデータセットが最後に更新されたのはいつですか？」
パラメーターの確認	「このデータセットで受け付けるパラメーターを教えてください」
DAX によるデータのクエリ	「[dataset] の地域別売上トップ 10 を取得する DAX クエリを実行してください」
データ品質の分析	「Sales データセットにはどのようなテーブルがありますか？」
インサイトの抽出	「Financial データセットのすべてのメジャーの一覧を取得してください」

📋 前提条件

• Azure AD サービスプリンシパル：認証に必要です。設定方法については、以下のAzure AD の設定の手順に従ってください。

🔐 Azure AD の設定

サーバーをインストールする前に、PowerBI へのアクセス権を持つ Azure AD アプリケーションを設定する必要があります。

Azure AD アプリ登録の作成

1. Azure Portal にアクセスします
2. Azure Active Directory > App registrations に移動します
3. New registration をクリックします
4. 名前を入力します（例：「PowerBI MCP Server」）
5. Register をクリックします

認証情報の取得

登録後、次の値を取得します。

• Tenant ID：アプリの概要ページにあります（Directory ID）
• Client ID：アプリの概要ページにあります（Application ID）
• Client Secret：
  • Certificates & secrets に移動します
  • New client secret をクリックします
  • 説明を追加し、有効期限を設定します
  • シークレットの Value をコピーします（表示できるのはこのときだけです！）

PowerBI でのサービスプリンシパルの有効化

1. PowerBI Admin Portal にアクセスします
2. Tenant settings > Developer settings に移動します
3. Service principals can use PowerBI APIs を有効にします
4. アプリをセキュリティグループに追加するか、組織全体に対して有効にします
5. Apply をクリックします

メモ

サービスプリンシパルは、明示的な権限（Admin、Member、Contributor ロール）が付与されたワークスペースにアクセスできます。

ワークスペースへのアクセス権の付与

アクセスする各ワークスペースで、次の操作を行います。

1. PowerBI でワークスペースに移動します
2. ワークスペースの設定（⚙️）> Access をクリックします
3. Add people or groups をクリックします
4. アプリ名を検索します
5. ロールを割り当てます：Admin、Member、または Contributor
6. Add をクリックします

📦 インストール

方法 0：PyPI からインストール（推奨）

PyPI に公開された後は、これが最も簡単なインストール方法です。

以下を MCP クライアントの設定ファイルに追加します。

Claude Desktop の場合（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": ["powerbi-mcp"],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Claude Code の場合（プロジェクトディレクトリの ./.mcp.json）：

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": ["powerbi-mcp"],
      "env": {}
    }
  }
}

Claude Code を使用する場合は、プロジェクトディレクトリ（Claude Code を実行するディレクトリ）に .env ファイルを作成します。

POWERBI_TENANT_ID=your-tenant-id-here
POWERBI_CLIENT_ID=your-client-id-here
POWERBI_CLIENT_SECRET=your-client-secret-here

ヒント

.env ファイルは作業ディレクトリに配置してください。サーバーのインストール先ではありません。

OpenCode の場合（~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp": {
      "type": "local",
      "command": ["uvx", "powerbi-mcp"],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

設定を追加したら、MCP クライアントを再起動します。

方法 1：GitHub から直接実行（開発用）

この方法では、リポジトリをクローンせずに uvx を使用して、GitHub からサーバーを直接実行します。

以下を MCP クライアントの設定ファイルに追加します。

Claude Desktop の場合（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Claude Code の場合（プロジェクトディレクトリの ./.mcp.json）：

{
  "mcpServers": {
    "powerbi-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "env": {}
    }
  }
}

Claude Code を使用する場合は、プロジェクトディレクトリ（Claude Code を実行するディレクトリ）に .env ファイルを作成します。

POWERBI_TENANT_ID=your-tenant-id-here
POWERBI_CLIENT_ID=your-client-id-here
POWERBI_CLIENT_SECRET=your-client-secret-here

ヒント

.env ファイルは作業ディレクトリに配置してください。サーバーのインストール先ではありません。

サーバーは、現在の作業ディレクトリにある .env ファイルから環境変数を自動的に読み込みます。

OpenCode の場合（~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/gurvinder-dhillon/powerbi-mcp@main",
        "run-server"
      ],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

設定を追加したら、MCP クライアントを再起動します。

方法 2：ローカルクローン（コントリビューター向け）

ローカルクローンから実行するコントリビューター向けの方法です。

1. リポジトリをクローンします。

git clone https://github.com/gurvinder-dhillon/powerbi-mcp.git
cd powerbi-mcp

2. 依存関係をインストールします。

uv sync

3. MCP クライアントの設定に追加します。

Claude Desktop の場合：

{
  "mcpServers": {
    "powerbi-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Claude Code の場合（プロジェクトディレクトリの ./.mcp.json）：

{
  "mcpServers": {
    "powerbi-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "env": {}
    }
  }
}

OpenCode の場合（~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "powerbi-mcp-local": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/powerbi-mcp",
        "run",
        "run-server"
      ],
      "enabled": true,
      "env": {
        "POWERBI_TENANT_ID": "your-tenant-id-here",
        "POWERBI_CLIENT_ID": "your-client-id-here",
        "POWERBI_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

/absolute/path/to/powerbi-mcp を、クローンしたリポジトリの実際のパスに置き換えてください。

Claude Code または OpenCode を使用する場合は、プロジェクトディレクトリに認証情報を記載した .env ファイルを作成します（形式については、上記の方法 1 の Claude Code セクションを参照してください）。

🚀 クイックスタート

インストールしたら、以下の手順を試して開始します。

1. 接続を確認：「アクセスできる PowerBI ワークスペースを教えてください」と Claude に尋ねます。
2. データを確認：「ワークスペース [workspace-name] 内のデータセットを表示してください」と尋ねます。
3. スキーマを確認：「データセット [dataset-name] にはどのテーブルがありますか？」と尋ねます。
4. クエリを実行：「[dataset-name] で次の DAX クエリを実行してください：EVALUATE TOPN(10, Sales)」と尋ねます。

🛠️ 使用可能なツール

ツール	説明	主なパラメーター
get_workspaces	アクセス可能な PowerBI ワークスペースを一覧表示	top, detail
get_datasets	ワークスペースまたは「My workspace」のデータセットを取得	workspace_id, detail
get_dataset	スキーマを含むデータセットの詳細情報を取得	dataset_id, workspace_id, detail
get_reports	ワークスペース内の PowerBI レポートを一覧表示	workspace_id, format, detail
get_refresh_history	ステータスやタイムスタンプ付きでデータセットの更新履歴を取得	dataset_id, workspace_id, top, format
get_parameters	データセットのパラメーターと現在の値を一覧表示	dataset_id, workspace_id, format, detail
query_dataset	データセットに対して DAX クエリを実行	dataset_id, dax_query, workspace_id

ツールの詳細

1. get_workspaces

サービスプリンシパルがアクセスできる PowerBI ワークスペースを一覧表示します。

パラメーター：

• top（任意）：返すワークスペースの数（デフォルト：100、最大：5000）
• detail（任意）：詳細度。「concise」、「normal」、「full」から選択します（デフォルト：「normal」）

2. get_datasets

ワークスペースまたは「My workspace」のデータセット一覧を取得します。

パラメーター：

• workspace_id（任意）：ワークスペース ID。「My workspace」の場合は省略します。
• detail（任意）：詳細度。「concise」、「normal」、「full」から選択します（デフォルト：「normal」）

3. get_dataset

スキーマやテーブルなど、特定のデータセットに関する詳細情報を取得します。

パラメーター：

• dataset_id（必須）：データセット ID
• workspace_id（任意）：ワークスペース ID（「My workspace」の場合は省略）
• detail（任意）：詳細度 — 「concise」、「normal」、「full」（既定値：「normal」）

4. get_reports

ワークスペース内の PowerBI レポートを一覧表示します。

パラメーター：

• workspace_id（任意）：ワークスペース ID（「My workspace」の場合は省略）
• format（任意）：応答形式 — 「markdown」または「json」（既定値：「markdown」）
• detail（任意）：詳細度 — 「concise」または「normal」（既定値：「concise」）

5. get_refresh_history

データセットの更新履歴を取得し、最近の更新操作を表示します。

パラメーター：

• dataset_id（必須）：データセット ID
• workspace_id（任意）：ワークスペース ID（「My workspace」の場合は省略）
• top（任意）：返す更新レコード数（既定値：5、最大：60）
• format（任意）：応答形式 — 「markdown」または「json」（既定値：「markdown」）

6. get_parameters

データセットで定義されたパラメーターを取得します。

パラメーター：

• dataset_id（必須）：データセット ID
• workspace_id（任意）：ワークスペース ID（「My workspace」の場合は省略）
• format（任意）：応答形式 — 「markdown」または「json」（既定値：「markdown」）
• detail（任意）：詳細度 — 「concise」または「normal」（既定値：「normal」）

注： SQL、Oracle、Teradata、SAP HANA DirectQuery 接続を使用するデータセット、または XMLA エンドポイント経由で変更されたデータセットはサポートされていません。

7. query_dataset

データセットに対して DAX クエリを実行します。

パラメーター：

• dataset_id（必須）：データセット ID
• dax_query（必須）：DAX クエリ（「EVALUATE」で始まる必要があります）
• workspace_id（任意）：ワークスペース ID（「My workspace」の場合は省略）

DAX クエリの例

基本的なテーブルスキャン：

EVALUATE
'Sales'

並べ替えを使用した上位 N 件の取得：

EVALUATE
TOPN(10, 'Sales', [Amount], DESC)

フィルター処理した結果：

EVALUATE
FILTER('Sales', [Year] = 2024)

計算列：

EVALUATE
ADDCOLUMNS(
    'Sales',
    "Profit", [Revenue] - [Cost]
)

集計サマリー：

EVALUATE
SUMMARIZE(
    'Sales',
    'Product'[Category],
    "Total Sales", SUM('Sales'[Amount])
)

⚠️ トラブルシューティング

認証エラー

エラー：「Authentication failed」

• POWERBI_TENANT_ID、POWERBI_CLIENT_ID、POWERBI_CLIENT_SECRET が正しいことを確認してください
• Azure AD でクライアントシークレットの有効期限が切れていないことを確認してください
• PowerBI Admin Portal でサービスプリンシパルが有効になっていることを確認してください

権限エラー

エラー：「403 Forbidden」または「Access denied」

• サービスプリンシパルにワークスペースへのアクセス権が付与されていることを確認してください
• ワークスペースのロールが Admin、Member、Contributor のいずれかであることを確認してください（API アクセスには Viewer では不十分です）
• PowerBI Admin Portal で「Service principals can use PowerBI APIs」が有効になっていることを確認してください

接続の問題

MCP クライアントにサーバーが表示されない

• 設定を追加した後、MCP クライアントを再起動してください
• 設定ファイルの構文を確認してください（JSON が有効である必要があります）
• ローカルクローンの場合は、絶対パスが正しいことを確認してください

ツールが動作しない

• 認証情報が設定されていることを確認してください
• 詳細なエラーメッセージを確認するため、MCP クライアントのログを確認してください
• Claude Code の場合は、.env ファイルが現在の作業ディレクトリにあることを確認してください

📚 リソース

• PowerBI REST API リファレンス
• Model Context Protocol
• DAX Guide
• Azure AD アプリ登録

💬 フィードバックとサポート

• 問題：GitHub Issues からバグを報告したり、機能をリクエストしたりできます
• ディスカッション：GitHub Discussions で質問してください
• プルリクエスト：コントリビューションを歓迎します！DEVELOPER_GUIDE.md をご覧ください

🤝 コントリビューション

このプロジェクトの開発やコントリビューションについては、DEVELOPER_GUIDE.md をご覧ください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。