Azure Data Explorer MCP Server

Azure Data Explorer MCP サーバー

Model Context Protocol（MCP）サーバーは、AI アシスタントが標準化されたインターフェースを通じて KQL クエリを実行し、Azure Data Explorer（ADX/Kusto）データベースを探索できるようにします。

このサーバーは、Azure Data Explorer および Eventhouse（Microsoft Fabric 内）のクラスターへのシームレスなアクセスを提供し、AI アシスタントが強力な Kusto Query Language を使用してデータをクエリおよび分析できるようにします。

機能

クエリの実行

• KQL クエリの実行 - ADX データベースに対して任意の KQL クエリを実行します
• 構造化された結果 - 使いやすい JSON 形式で結果を取得します

データベースの検出

• テーブルの一覧表示 - データベース内のすべてのテーブルを検出します
• スキーマの表示 - テーブルのスキーマと列の型を調べます
• サンプルデータ - サンプル件数を設定してテーブルの内容をプレビューします
• テーブル統計 - 行数やストレージサイズなど、詳細なメタデータを取得します

認証

• DefaultAzureCredential - Azure CLI、Managed Identity などをサポートします
• Workload Identity - AKS ワークロード ID をネイティブにサポートします
• 柔軟な認証情報 - 複数の Azure 認証方式に対応します

デプロイ方法

• 複数のトランスポート - stdio（デフォルト）、HTTP、Server-Sent Events（SSE）
• Docker のサポート - セキュリティのベストプラクティスに従った、本番環境対応のコンテナーイメージ
• Dev Container - GitHub Codespaces によるシームレスな開発環境

ツールの一覧は設定可能なため、MCP クライアントで利用できるようにするツールを選択できます。一部の機能を使用しない場合や、コンテキストウィンドウを使いすぎたくない場合に便利です。

使い方

1. Azure CLI を使用して、ADX クラスターへのアクセス許可を持つ Azure アカウントにログインします。

2. .env ファイルまたはシステム環境変数を使用して、ADX クラスターの環境変数を設定します。

# Required: Azure Data Explorer configuration
ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net
ADX_DATABASE=your_database

# Optional: Azure Workload Identity credentials 
# AZURE_TENANT_ID=your-tenant-id
# AZURE_CLIENT_ID=your-client-id 
# ADX_TOKEN_FILE_PATH=/var/run/secrets/azure/tokens/azure-identity-token

# Optional: Custom MCP Server configuration
ADX_MCP_SERVER_TRANSPORT=stdio # Choose between http/sse/stdio, default = stdio

# Optional: Only relevant for non-stdio transports
ADX_MCP_BIND_HOST=127.0.0.1 # default = 127.0.0.1
ADX_MCP_BIND_PORT=8080 # default = 8080

Azure Workload Identity のサポート

このサーバーは、ワークロード ID が設定された Azure Kubernetes Service（AKS）環境で実行する場合、WorkloadIdentityCredential をデフォルトで使用するようになりました。必要な環境変数が設定されている場合は、WorkloadIdentityCredential の使用が優先されます。

Azure Workload Identity を使用する AKS では、次の設定だけで十分です。

1. ポッドに AZURE_TENANT_ID および AZURE_CLIENT_ID 環境変数が設定されていることを確認します
2. トークンファイルがデフォルトのパスにマウントされていることを確認するか、ADX_TOKEN_FILE_PATH でカスタムパスを指定します

これらの環境変数が設定されていない場合、サーバーは複数の認証方式を順番に試す DefaultAzureCredential に自動的にフォールバックします。

3. サーバーの設定をクライアント設定ファイルに追加します。たとえば、Claude Desktop の場合は次のようにします。

{
  "mcpServers": {
    "adx": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to adx-mcp-server directory>",
        "run",
        "src/adx_mcp_server/main.py"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database"
      }
    }
  }
}

注：Claude Desktop で Error: spawn uv ENOENT が表示される場合は、uv のフルパスを指定するか、設定で環境変数 NO_UV=1 を設定する必要があります。

Docker の使用

このプロジェクトは、デプロイと分離を簡単にするために Docker をサポートしています。

Docker イメージのビルド

次のコマンドを使用して Docker イメージをビルドします。

docker build -t adx-mcp-server .

Docker での実行

Docker を使用して、いくつかの方法でサーバーを実行できます。

docker run を直接使用する場合：

docker run -it --rm \
  -e ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net \
  -e ADX_DATABASE=your_database \
  -e AZURE_TENANT_ID=your_tenant_id \
  -e AZURE_CLIENT_ID=your_client_id \
  adx-mcp-server

docker-compose を使用する場合：

Azure Data Explorer の認証情報を含む .env ファイルを作成してから、次のコマンドを実行します。

docker-compose up

Claude Desktop で Docker を使って実行する

コンテナ化されたサーバーを Claude Desktop で使用するには、環境変数を指定して Docker を使うように設定を更新します。

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE",
        "-e", "AZURE_TENANT_ID",
        "-e", "AZURE_CLIENT_ID",
        "-e", "ADX_TOKEN_FILE_PATH",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database",
        "AZURE_TENANT_ID": "your_tenant_id",
        "AZURE_CLIENT_ID": "your_client_id",
        "ADX_TOKEN_FILE_PATH": "/var/run/secrets/azure/tokens/azure-identity-token"
      }
    }
  }
}

この設定では、変数名だけを指定した -e フラグを使い、実際の値を env オブジェクトに指定することで、Claude Desktop から Docker コンテナに環境変数を渡します。

HTTP トランスポートで Docker を使う

HTTP モードでデプロイする場合は、次の Docker 設定を使用できます。

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE", 
        "-e", "ADX_MCP_SERVER_TRANSPORT",
        "-e", "ADX_MCP_BIND_HOST",
        "-e", "ADX_MCP_BIND_PORT",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database",
        "ADX_MCP_SERVER_TRANSPORT": "http",
        "ADX_MCP_BIND_HOST": "0.0.0.0",
        "ADX_MCP_BIND_PORT": "8080"
      }
    }
  }
}

Dev Container／GitHub Codespace として使う

このリポジトリは、シームレスな開発体験を実現する開発コンテナとしても使用できます。Dev Container の設定は devcontainer-feature/adx-mcp-server フォルダーにあります。

詳しくは、Dev Container の README をご覧ください。

開発

コントリビューションを歓迎します！ご提案や改善点がある場合は、イシューを作成するか、プルリクエストを送信してください。

このプロジェクトでは、依存関係の管理に uv を使用しています。お使いのプラットフォーム向けの手順に従って uv をインストールしてください。

curl -LsSf https://astral.sh/uv/install.sh | sh

その後、次のコマンドで仮想環境を作成し、依存関係をインストールできます。

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

プロジェクト構成

このプロジェクトは src ディレクトリー構成で整理されています。

adx-mcp-server/
├── src/
│   └── adx_mcp_server/
│       ├── __init__.py      # Package initialization
│       ├── server.py        # MCP server implementation
│       ├── main.py          # Main application logic
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose configuration
├── .dockerignore            # Docker ignore file
├── pyproject.toml           # Project configuration
└── README.md                # This file

テスト

このプロジェクトには、機能を確認し、リグレッションの防止に役立つ包括的なテストスイートが含まれています。

pytest でテストを実行します。

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

テストは次のように分類されています。

• 設定の検証テスト
• サーバー機能テスト
• エラー処理テスト
• メインアプリケーションのテスト

新しい機能を追加する際は、対応するテストも追加してください。

利用可能なツール

ツール	カテゴリー	説明	パラメーター
execute_query	クエリー	Azure Data Explorer に対して KQL クエリーを実行します	query（string）- 実行する KQL クエリー
list_tables	検出	設定されたデータベース内のすべてのテーブルを一覧表示します	なし
get_table_schema	検出	特定のテーブルのスキーマを取得します	table_name（string）- テーブル名
sample_table_data	検出	テーブルのサンプルデータを取得します	table_name（string）、sample_size（int、既定値：10）
get_table_details	検出	テーブルの統計情報とメタデータを取得します	table_name（string）- テーブル名

設定

必須の環境変数

変数	説明	例
ADX_CLUSTER_URL	Azure Data Explorer クラスターの URL	https://yourcluster.region.kusto.windows.net
ADX_DATABASE	接続先のデータベース名	your_database

任意の環境変数

Azure Workload Identity（AKS 用）

変数	説明	既定値
AZURE_TENANT_ID	Azure AD テナント ID	-
AZURE_CLIENT_ID	Azure AD クライアント／アプリケーション ID	-
ADX_TOKEN_FILE_PATH	Workload Identity トークンファイルのパス	/var/run/secrets/azure/tokens/azure-identity-token

MCP サーバーの設定

変数	説明	既定値
ADX_MCP_SERVER_TRANSPORT	トランスポートモード：stdio、http、または sse	stdio
ADX_MCP_BIND_HOST	バインドするホスト（HTTP／SSE のみ）	127.0.0.1
ADX_MCP_BIND_PORT	バインドするポート（HTTP／SSE のみ）	8080

ロギング

変数	説明	既定値
LOG_LEVEL	ログレベル：DEBUG、INFO、WARNING、ERROR	INFO

ライセンス

MIT

---