Airflow MCPサーバーでDAGの実行状況をClaudeに監視させる

Airflow MCPサーバーとは何か

Airflow MCPサーバー(astro-airflow-mcp)は、Apache AirflowのREST APIをMCPツールとして公開するサーバーです。Apache Airflowプロジェクトそのものではなく、Airflow開発を主導する商用ベンダーAstronomerが提供しています。オープンソースで公開されていますが、この違いはドキュメントに明記されています。

FastMCPで実装され、DAG・タスク・プール・変数・接続・アセットといったAirflowの主要リソースをツール化しています。用途は大きく2つで、DAGの実行状況を自然言語で照会する運用監視と、失敗したタスクインスタンスのログを辿る原因調査です。パッケージ名はastro-airflow-mcp、ライセンスはApache 2.0で公開されています。

Claude Codeへの接続方法

インストール不要で、uvxがPyPIから直接実行します。PyPI公開版の最新は0.9.1です。

claude mcp add airflow -- uvx astro-airflow-mcp --transport stdio

デフォルトの接続先はAstro CLIのローカル環境(http://localhost:8080)です。リモートのAirflowインスタンスに繋ぐ場合は、認証用の環境変数を-eで渡します。

claude mcp add airflow \
  -e AIRFLOW_API_URL=https://your-airflow.example.com \
  -e AIRFLOW_USERNAME=admin \
  -e AIRFLOW_PASSWORD=admin \
  -- uvx astro-airflow-mcp --transport stdio

--transport stdioの指定は必須です。省略するとサーバーはHTTPモードで起動し、Claude Codeのstdio接続と噛み合いません。

認証はAirflowのバージョンで挙動が変わる

Airflow 2.xと3.xでは認証APIが異なり、astro-airflow-mcpはアダプターパターンで両方を自動判定します。Airflow 2.xはBasic認証(/api/v1)、Airflow 3.xはユーザー名とパスワードからOAuth2トークン交換を行う方式(/api/v2)という違いがあり、AIRFLOW_USERNAME/AIRFLOW_PASSWORDを渡すだけでどちらの方式かはサーバー側が自動で切り替えます。

固定のBearerトークンを使う場合はAIRFLOW_AUTH_TOKENが両バージョンで共通して使えます。起動時にAPIエンドポイントへプローブを送ってバージョンを検出するため、接続先のAirflowが2.xか3.xかを事前に意識する必要はありません。

使えるツールの分類

ツールは「エージェント向けに複数の情報をまとめて返す統合ツール」と「個別リソースを扱うコアツール」の2層構成です。

list_connectionsは認証情報を含めずに返す設計になっており、接続一覧をClaudeに見せても資格情報がやり取りに乗ることはありません。取得したログが長大になりがちなタスクは、MAX_MCP_OUTPUT_TOKENSでMCPツール出力の上限を調整すると読み込みが安定します。

プール(list_pools)や変数(list_variables)は、DAGの並列実行数やDAG間で共有する設定値を管理するAirflow標準の仕組みです。「etl_poolの空きスロット数を教えて」と聞けばget_poolが呼ばれ、リソース競合でタスクが待たされていないかをその場で確認できます。アセット系のツール(list_assets)はAirflow 2.xのデータセットとAirflow 3.xのアセットを同じ名前で扱えるようにしたもので、DAG間のデータ依存関係を辿るときに使えます。

失敗したDAGの原因調査を自然言語で任せる

日々の運用では、統合ツールに寄せた聞き方がそのまま効きます。「get_system_healthで今のAirflowの状態を教えて」と頼めばインポートエラーや警告まで含めたサマリーが返り、「daily_sales_etlというDAGの直近の失敗runを調査して」と伝えるとdiagnose_dag_runが該当runの失敗タスクとログを1回でまとめて返します。

個別のDAGを深掘りしたいときはexplore_dagが向いています。「daily_sales_etlの全体像を見せて」と聞けば、メタデータ・タスク構成・直近の実行履歴・ソースコードがまとめて返るため、初めて触るDAGの構造把握にも使えます。トリガーや一時停止のような書き込み系操作も同じ調子の指示で実行できますが、本番のスケジューラに影響するため、Claude Codeの権限確認プロンプトを無効化しない運用が安全です。

プロバイダーやオペレーターの情報も自然言語で引ける

DAGの実行状況だけでなく、Airflowのプロバイダーパッケージが持つオペレーターやフックの仕様もaf registry系のツールで調べられます。「amazonプロバイダーが提供しているオペレーター一覧を教えて」と聞けば、稼働中のAirflowインスタンスに接続していなくても該当プロバイダーのモジュール構成が返ります。問い合わせ結果はキャッシュされるため、繰り返しの照会でも外部への通信を抑える設計です。

新しいDAGを書く前に「S3からのファイル取得に使えるフックとその引数を教えて」のように尋ねれば、公式ドキュメントを開かずにオペレーターの引数仕様を確認できます。DAGの実行監視だけでなく、DAG開発時のリファレンス代わりとしても使える範囲です。

スタンドアロンとプラグインモードの違い

astro-airflow-mcpはデフォルトのスタンドアロンサーバーに加えて、Airflow 3.x環境ではAirflowのWebサーバーに直接マウントするプラグインモードを持ちます。プラグインモードではhttps://your-airflow/mcp/v1/にMCPエンドポイントが立ち上がり(ポートはAirflowウェブサーバーの既定値、通常8080)、別プロセスを常駐させずに済みます。

複数のクライアントから同じMCPサーバーに繋ぎたい場合は、HTTPモードのスタンドアロンサーバーを立ててhttp://localhost:8000/mcpで共有する構成が公式ドキュメントで案内されています。1人の開発者がClaude Codeから使うだけなら--transport stdioのスタンドアロン起動で十分です。

af CLIでターミナルから直接操作する

astro-airflow-mcpパッケージには、MCPサーバーとは別にafというCLIツールが同梱されています。af dags listやaf runs list --dag-id <dag_id>のようにコマンドラインから直接AirflowのREST APIを叩けるツールで、出力はすべてJSONなのでjqと組み合わせて使えます。

af health
af dags explore daily_sales_etl
af runs list --dag-id daily_sales_etl | jq '.dag_runs[] | select(.state == "failed")'

MCP経由の自然言語操作と、afによるスクリプト向けの直接操作を使い分けられる構成です。

afは複数のAirflowインスタンスをaf instance addで登録し、af instance use prodのように切り替えて使う設計も持っています。ローカル・ステージング・本番といった複数環境を横断してDAGの状態を確認する開発チームでは、MCPサーバー自体をインスタンスごとに登録し直す代わりに、af側でインスタンスを切り替えてから必要な情報だけをMCP経由の会話に貼り戻す運用もできます。設定は~/.astro/config.yaml(個人用)とプロジェクト直下の.astro/config.yaml(チーム共有用)の2階層で管理され、後者にトークンを直書きしたくない場合は${AIRFLOW_PROD_TOKEN}のような環境変数展開で参照する構成が案内されています。

導入でつまずきやすいポイント

astro-airflow-mcpのGitHubリポジトリは2026年にAstronomerのagentsモノレポへ移設されています。旧リポジトリ(astronomer/astro-airflow-mcp)にはリダイレクトの警告が残るだけなので、Issue登録やドキュメント参照はastronomer/agents配下のastro-airflow-mcpディレクトリを見に行く必要があります。

af CLIは、接続先のAirflowインスタンスが未設定の場合デフォルトではhttp://localhost:8080にフォールバックします。CI環境など「Airflowが無い」ことを明示したい場面では、AIRFLOW_API_URL=""を空文字で設定すると、フォールバックせず明確なエラーで停止します。自動化スクリプトに組み込むときはこの空文字指定を使うと事故を防げます。

trigger_dagやpause_dag、タスクを再実行させるget_task_instanceまわりの操作は本番のスケジューラを直接動かすため、Kubernetes MCPサーバーのような他のインフラ系MCPと同じく、書き込み系ツールを無人のルーチンに開放しない運用が前提になります。Claude Codeの承認プロンプトを対話セッションでは有効なままにし、無人実行が必要な監視タスクは読み取り系ツールだけで完結させる設計にすると事故のリスクを抑えられます。

社内の自己署名証明書やプライベートCAを使ったAirflow環境に繋ぐ場合、MCPサーバー自体には検証スキップの起動オプションが無いため、af instance add側の--no-verify-sslや--ca-certでCLIツール経由の接続を先に確立してから証明書の妥当性を確認する手順が現実的です。

まとめ

Airflow MCPサーバーは、Astronomerが提供する非公式ながら実用的なMCP実装で、DAGの実行状況照会と失敗原因の調査を自然言語のやり取りに落とし込めます。Airflow 2.xと3.xの認証方式の違いはサーバー側が自動吸収するため、利用者が意識するのは接続先URLと認証情報の3変数だけです。運用の起点はget_system_healthとdiagnose_dag_runで、まずこの2つから使い始めるのが実践的です。DAG開発時のオペレーター調査まで含めると、監視ツールというより日々の開発を横断する相棒に近い立ち位置です。

よくある質問

Apache Airflow公式のMCPサーバーは別に存在するか

Apache Airflowプロジェクト自体は公式MCPサーバーを提供していません。astro-airflow-mcpは、Airflowの商用マネージドサービスを展開するAstronomerが公開する実装です。

ローカルのAstro CLI環境以外でも使えるか

使えます。AIRFLOW_API_URLで任意のAirflowインスタンスを指定できるため、Astro CLI以外でホストされたAirflow環境にも同じ手順で接続できます。

Airflow 2.xと3.xのどちらの環境でも同じツールが使えるか

コアツールの大半は両バージョンで共通して動きますが、DAG実行統計を返すget_dag_statsのようにAirflow 3.x限定のツールもあります。バージョン検出は起動時に自動で行われるため、接続先が対応していないツールは呼び出し時にその旨がエラーとして返ります。