mcp-server-apache-airflow

mcp-server-apache-airflow

Apache Airflow 用の Model Context Protocol（MCP）サーバー実装です。MCP クライアントとシームレスに連携できます。このプロジェクトでは、Model Context Protocol を通じて Apache Airflow とやり取りするための標準化された方法を提供します。

概要

このプロジェクトは、Apache Airflow の REST API をラップする Model Context Protocol サーバーを実装し、MCP クライアントが標準化された方法で Airflow とやり取りできるようにします。互換性と保守性を確保するため、公式の Apache Airflow クライアントライブラリを使用します。

機能の実装状況

機能	API パス	ステータス
DAG 管理
DAG の一覧表示	/api/v1/dags	✅
DAG の詳細取得	/api/v1/dags/{dag_id}	✅
DAG の一時停止	/api/v1/dags/{dag_id}	✅
DAG の一時停止解除	/api/v1/dags/{dag_id}	✅
DAG の更新	/api/v1/dags/{dag_id}	✅
DAG の削除	/api/v1/dags/{dag_id}	✅
DAG ソースの取得	/api/v1/dagSources/{file_token}	✅
複数の DAG のパッチ適用	/api/v1/dags	✅
DAG ファイルの再解析	/api/v1/dagSources/{file_token}/reparse	✅
DAG 実行
DAG 実行の一覧表示	/api/v1/dags/{dag_id}/dagRuns	✅
DAG 実行の作成	/api/v1/dags/{dag_id}/dagRuns	✅
DAG 実行の詳細取得	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
DAG 実行の更新	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
DAG 実行の削除	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
DAG 実行の一括取得	/api/v1/dags/~/dagRuns/list	✅
DAG 実行のクリア	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/clear	✅
DAG 実行のメモ設定	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/setNote	✅
上流データセットイベントの取得	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamDatasetEvents	✅
タスク
DAG タスクの一覧表示	/api/v1/dags/{dag_id}/tasks	✅
タスクの詳細取得	/api/v1/dags/{dag_id}/tasks/{task_id}	✅
タスクインスタンスの取得	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
タスクインスタンスの一覧表示	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances	✅
タスクインスタンスの更新	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
タスクインスタンスのログ取得	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/logs/{task_try_number}	✅
タスクインスタンスのクリア	/api/v1/dags/{dag_id}/clearTaskInstances	✅
タスクインスタンスの状態設定	/api/v1/dags/{dag_id}/updateTaskInstancesState	✅
タスクインスタンスの試行一覧表示	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/tries	✅
変数
変数の一覧表示	/api/v1/variables	✅
変数の作成	/api/v1/variables	✅
変数の取得	/api/v1/variables/{variable_key}	✅
変数の更新	/api/v1/variables/{variable_key}	✅
変数の削除	/api/v1/variables/{variable_key}	✅
接続
接続の一覧表示	/api/v1/connections	✅
接続の作成	/api/v1/connections	✅
接続の取得	/api/v1/connections/{connection_id}	✅
接続の更新	/api/v1/connections/{connection_id}	✅
接続の削除	/api/v1/connections/{connection_id}	✅
接続のテスト	/api/v1/connections/test	✅
プール
プールの一覧表示	/api/v1/pools	✅
プールの作成	/api/v1/pools	✅
プールの取得	/api/v1/pools/{pool_name}	✅
プールの更新	/api/v1/pools/{pool_name}	✅
プールの削除	/api/v1/pools/{pool_name}	✅
XCom
XCom の一覧表示	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries	✅
XCom エントリの取得	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries/{xcom_key}	✅
データセット
データセットの一覧表示	/api/v1/datasets	✅
データセットの取得	/api/v1/datasets/{uri}	✅
データセットイベントの取得	/api/v1/datasetEvents	✅
データセットイベントの作成	/api/v1/datasetEvents	✅
DAG のキュー済みデータセットイベントの取得	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
DAG のキュー済みデータセットイベント一覧の取得	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
DAG のキュー済みデータセットイベントの削除	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
DAG のキュー済みデータセットイベント一覧の削除	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
データセットのキュー済みイベント一覧の取得	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
データセットのキュー済みイベント一覧の削除	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
モニタリング
ヘルス情報の取得	/api/v1/health	✅
DAG 統計情報
DAG 統計情報の取得	/api/v1/dags/statistics	✅
設定
設定の取得	/api/v1/config	✅
プラグイン
プラグインの取得	/api/v1/plugins	✅
プロバイダー
プロバイダーの一覧表示	/api/v1/providers	✅
イベントログ
イベントログの一覧表示	/api/v1/eventLogs	✅
イベントログの取得	/api/v1/eventLogs/{event_log_id}	✅
システム
インポートエラーの取得	/api/v1/importErrors	✅
インポートエラーの詳細取得	/api/v1/importErrors/{import_error_id}	✅
ヘルスステータスの取得	/api/v1/health	✅
バージョンの取得	/api/v1/version	✅

セットアップ

依存関係

このプロジェクトは、公式の Apache Airflow クライアントライブラリ（apache-airflow-client）に依存しています。このパッケージをインストールすると、自動的にインストールされます。

環境変数

以下の環境変数を設定します。

AIRFLOW_HOST=<your-airflow-host>        # Optional, defaults to http://localhost:8080
AIRFLOW_API_VERSION=v1                  # Optional, defaults to v1
READ_ONLY=true                          # Optional, enables read-only mode (true/false, defaults to false)

認証

以下の認証方法から1つ選択します。

基本認証（デフォルト）：

AIRFLOW_USERNAME=<your-airflow-username>
AIRFLOW_PASSWORD=<your-airflow-password>

JWT トークン認証：

AIRFLOW_JWT_TOKEN=<your-jwt-token>

JWT トークンを取得するには、Airflow の認証エンドポイントを使用できます。

ENDPOINT_URL="http://localhost:8080"  # Replace with your Airflow endpoint
curl -X 'POST' \
  "${ENDPOINT_URL}/auth/token" \
  -H 'Content-Type: application/json' \
  -d '{ "username": "<your-username>", "password": "<your-password>" }'

注：JWT トークンと基本認証の認証情報が両方とも指定されている場合は、JWT トークンが優先されます。

Claude Desktop での使用

claude_desktop_config.json に追加します。

基本認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password"
      }
    }
  }
}

JWT トークン認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

安全性のため、読み取り専用モードの使用をおすすめします。

基本認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password",
        "READ_ONLY": "true"
      }
    }
  }
}

JWT トークン認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow", "--read-only"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

uv を使用した別の設定方法：

基本認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-apache-airflow",
        "run",
        "mcp-server-apache-airflow"
      ],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password"
      }
    }
  }
}

JWT トークン認証：

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-apache-airflow",
        "run",
        "mcp-server-apache-airflow"
      ],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

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

API グループの選択

--apis フラグを設定して、使用する API グループを選択できます。

uv run mcp-server-apache-airflow --apis dag --apis dagrun

デフォルトでは、すべての API が使用されます。

指定可能な値は以下のとおりです。

• config
• connections
• dag
• dagrun
• dagstats
• dataset
• eventlog
• importerror
• monitoring
• plugin
• pool
• provider
• taskinstance
• variable
• xcom

読み取り専用モード

--read-only フラグを使用するか、READ_ONLY=true 環境変数を設定すると、サーバーを読み取り専用モードで実行できます。このモードでは、読み取り操作（GET リクエスト）を行うツールのみが公開され、リソースの作成、更新、削除を行うツールは除外されます。

コマンドラインフラグを使用する場合：

uv run mcp-server-apache-airflow --read-only

環境変数を使用する場合：

READ_ONLY=true uv run mcp-server-apache-airflow

読み取り専用モードでは、以下のようなツールのみがサーバーから公開されます。

• DAG、DAG 実行、タスク、変数、接続などの一覧表示
• 特定のリソースの詳細取得
• 設定および監視情報の読み取り
• 接続テスト（破壊的な操作ではありません）

DAG、変数、接続などの作成・更新・削除、DAG 実行のトリガーといった書き込み操作は、読み取り専用モードでは利用できません。

読み取り専用モードと API グループの選択を組み合わせることもできます。

uv run mcp-server-apache-airflow --read-only --apis dag --apis variable

手動実行

サーバーは手動で実行することもできます。

make run

make run では、以下のオプションを使用できます。

オプション：

• --port：SSE のリッスンに使用するポート（デフォルト：8000）
• --transport：トランスポートの種類（stdio/sse/http、デフォルト：stdio）

同じパラメーターを受け付ける SSE サーバーを直接実行することもできます。

make run-sse

また、以下のコマンドのように、uv を使用してサービスを直接起動することもできます。

uv run src --transport http --port 8080

Smithery 経由でのインストール

Smithery 経由で Apache Airflow MCP Server を Claude Desktop に自動インストールするには：

npx -y @smithery/cli install @yangkyeongmo/mcp-server-apache-airflow --client claude

開発

開発環境のセットアップ

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

git clone https://github.com/yangkyeongmo/mcp-server-apache-airflow.git
cd mcp-server-apache-airflow

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

uv sync --dev

3. 環境変数を設定する .env ファイルを作成します（開発時は省略可能です）。

touch .env

注：テストの実行に環境変数は必要ありません。開発およびテストでは、AIRFLOW_HOST のデフォルト値は http://localhost:8080 です。

テストの実行

このプロジェクトではテストに pytest を使用しており、以下のコマンドを利用できます。

# Run all tests
make test

コード品質

# Run linting
make lint

# Run code formatting
make format

継続的インテグレーション

このプロジェクトには、以下を自動的に実行する GitHub Actions ワークフロー（.github/workflows/test.yml）が含まれています。

• Python 3.10、3.11、3.12 でテストを実行
• ruff を使用してリンティングチェックを実行
• main ブランチへのすべてのプッシュおよびプルリクエストで実行

CI パイプラインにより、変更がマージされる前に、サポート対象の Python バージョン全体でコード品質と互換性が確保されます。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

pyproject.toml の project.version が更新されると、パッケージは自動的に PyPI にデプロイされます。 バージョン管理にはセマンティックバージョニングに従ってください。

コアロジックに変更を適用するため、プルリクエストにはバージョンの更新も含めてください。

ライセンス

MIT ライセンス