MCP-Airflow-API

Sat, 02 May 2026 07:29:22 +0000

What is MCP-Airflow-API?

A Model Context Protocol (MCP) server that brings natural language
operations to Apache Airflow workflow management. Works with Claude
Desktop, Claude Code, OpenWebUI, or any MCP-compatible LLM client.

Stop juggling Airflow Web UI, REST API curl commands, and CLI sessions.
Just ask:

"Show me all currently running DAGs"
"Trigger DAG 'example_complex' and show me the run status"
"List failed task instances from yesterday with logs"
"Show task durations for the latest run of etl_pipeline"
"Find DAGs containing 'ETL' that haven't run in the last 24 hours"

Why I built it

Day-to-day Airflow operations — investigating failed DAG runs, checking
task logs, managing pools and variables, analyzing event logs — require
constant context switching between the Web UI, REST API documentation,
and CLI. I wanted an LLM agent that could translate operator intent
into precise Airflow API calls across both Airflow 2.x and 3.0+
clusters.

Key Features

Dual API Version Support: Single MCP server handles both Airflow
API v1 (2.x) and v2 (3.0+) via AIRFLOW_API_VERSION environment
variable — switch versions without reconfiguration
45 Tools: 43 shared tools + 2 v2-exclusive asset management tools
DAG Operations: Trigger, pause, resume, list, filter DAGs with
pagination support for 1000+ DAG environments
Task Instance Analysis: Filter by state, pool, duration, time
range; retrieve logs and extra links
Smart Date Handling: Natural language dates ("yesterday",
"last 3 days", "this morning") auto-converted to API parameters
Pool, Variable, Connection Management: Full CRUD via natural
language
Configuration Inspection: Search and filter Airflow config
sections and options
Event Log Analysis: DAG event summaries, import error reports,
per-DAG event tracking
XCom Management: List and retrieve XCom entries by task and run
Asset Management (v2): Data-aware scheduling support for
Airflow 3.0+ assets and asset events
Multi-Cluster Support: Manage multiple Airflow versions
simultaneously via separate MCP server entries
Bearer Token Auth: Production-ready authentication for
streamable-http mode
Flexible Transports: stdio for local, streamable-http for
remote/Docker

Installation

PyPI package available:

uvx --python 3.12 mcp-airflow-api

Claude Desktop config:

{
  "mcpServers": {
    "mcp-airflow-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v2",
        "AIRFLOW_API_BASE_URL": "http://localhost:8080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    }
  }
}

Or run the full Docker Compose stack with MCP-Server, MCPO Proxy, and
OpenWebUI in 5 minutes. A companion repository (Airflow-Docker-Compose)
provides ready-to-use Airflow 2.x and 3.x test clusters.

Tech Stack

Python 3.12 + asyncio
FastMCP framework
Apache Airflow REST API v1 (2.x) and v2 (3.0+)
stdio and streamable-http transports

Looking for Feedback

Which Airflow areas should be enhanced next? (DAG-as-code editing?
Sensor-specific tools? Provider package introspection?)
How should destructive operations (clear DAG runs, delete
variables) be gated for safety?
Anyone running this against large production clusters with
thousands of DAGs — performance feedback welcome
Multi-tenant Airflow deployments — interest in workspace/team
scoping?

Repo: https://github.com/call518/MCP-Airflow-API
PyPI: https://pypi.org/project/MCP-Airflow-API/
DeepWiki: https://deepwiki.com/call518/MCP-Airflow-API
Test Clusters: https://github.com/call518/Airflow-Docker-Compose

⭐ Stars, issues, and PRs welcome. The codebase includes an
"Adding Custom Tools" guide for easy extension.