MCP-Airflow-API

Question

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

1. Which Airflow areas should be enhanced next? (DAG-as-code editing?
   Sensor-specific tools? Provider package introspection?)
2. How should destructive operations (clear DAG runs, delete
   variables) be gated for safety?
3. Anyone running this against large production clusters with
   thousands of DAGs — performance feedback welcome
4. 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.