Apache Airflow MCP Server

Independent community project; not affiliated with or endorsed by the Apache Software Foundation.

Published through PyPI, GHCR, and the official MCP Registry. Reproducible scan reports, dependency audits, SBOMs, and provenance are attached to each immutable release.

Connect Claude, Cursor, VS Code, or another MCP client to your Apache Airflow deployments and help agents diagnose failed DAGs.

Paste an Airflow UI link from a PagerDuty/Datadog alert and ask "why did this fail?" — the agent resolves the URL, finds the failed tasks, pulls log errors filtered and bounded before the MCP response, and can re-trigger or clear runs. Write tools carry destructive-operation annotations that MCP clients can use to request confirmation.

Highlights

• 🔍 Incident-response first — resolve Airflow UI URLs straight to the failing task, filter logs by error level with context lines, follow try_number semantics correctly (sensors included)
• 🏢 Multi-instance — one server for same-API-family dev/staging/prod targets, with per-instance credentials and an SSRF guard that rejects unknown hosts
• 🔒 Safety controls — opt-in read-only mode (AIRFLOW_MCP_READ_ONLY=true) that never registers write tools; write tools annotated as destructive; configured credentials are redacted from instance responses and operation logs
• 📉 Token-efficient — log tailing, level filtering, byte caps, and truncation metadata designed for LLM context windows
• 🧭 Airflow 2 and 3 — API v1/v2 adapters with live E2E against Airflow 2.11 and 3.3, including JWT auth
• 📎 Traceable — every response carries a request_id that matches the structured server logs

Quickstart

1. Install

uv tool install apache-airflow-mcp-server \
  --with 'apache-airflow-client==3.3.0'  # replace 3.3.0 with your Airflow version

Airflow 2.11? Use --with 'apache-airflow-client==2.10.0' instead; 2.10.0 is the final generated v1 client and targets Airflow 2's stable API. See Airflow compatibility before using a different release.

2. Connect your MCP client

The fastest path is a single instance configured entirely with environment variables — no config file needed.

claude mcp add airflow \
  --env AIRFLOW_MCP_HOST=https://airflow.example.com \
  --env AIRFLOW_MCP_USERNAME=admin \
  --env AIRFLOW_MCP_PASSWORD=your-password \
  --env AIRFLOW_MCP_READ_ONLY=true \
  -- uvx --from apache-airflow-mcp-server \
  --with apache-airflow-client==3.3.0 airflow-mcp --transport stdio

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

{
  "servers": {
    "airflow": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

AIRFLOW_MCP_HOST=https://airflow.example.com \
AIRFLOW_MCP_USERNAME=admin AIRFLOW_MCP_PASSWORD=your-password \
AIRFLOW_MCP_READ_ONLY=true \
airflow-mcp --transport http --host 127.0.0.1 --port 8765

{ "mcpServers": { "airflow": { "url": "http://127.0.0.1:8765/mcp" } } }

3. Ask your agent something

"Why did the latest run of etl_pipeline fail?"

"https://airflow.example.com/dags/etl_pipeline/grid — what happened here, and is it safe to clear?"

"Show the failed task's error context and tell me the smallest recovery action."

Airflow compatibility

The server talks to Airflow through the generated apache-airflow-client. For Airflow 3, match the client release to your Airflow release: generated models can change within a major version, and a newer client is not guaranteed to deserialize an older server's responses correctly. Airflow 2.11 uses the final v1 client release, 2.10.0, against Airflow 2's stable API.

When api_version isn't set, the server assumes the API matching the installed client (v1 for a 2.x client, v2 for 3.x). Set AIRFLOW_MCP_API_VERSION (or api_version: in the registry) explicitly to catch a major-version mismatch early.

One server process can currently load only one generated client major. All instances in a registry must therefore use the same API family; run separate MCP server processes for Airflow 2 and Airflow 3. Mixed-version support requires a future client-adapter change and is not advertised as working today.

Airflow 3 notes:

• Auth: bearer tokens are passed through as JWTs; basic credentials are automatically exchanged for a JWT via POST /auth/token and refreshed periodically (AIRFLOW_MCP_TOKEN_REFRESH_SECONDS, default 3600 — keep it below your deployment's JWT expiry, and note there is no automatic re-auth on 401 yet).
• execution_date ordering maps to logical_date, datasets map to assets, and UI links use the Airflow 3 route scheme. Tool names and the core workflow stay stable; documented fields and options can differ by API family.
• Clear options that no longer exist in Airflow 3 (include_subdags/include_parentdag, and the include_*/reset_dag_runs options of airflow_clear_dag_run) are rejected with INVALID_INPUT rather than silently narrowing a destructive operation.

Both client families are exercised on relevant pull requests and main pushes. Bug reports from real Airflow deployments are very welcome!

Configuration

Single instance (env vars only)

* provide either username+password or a token.

Multiple instances (registry YAML)

Point AIRFLOW_MCP_INSTANCES_FILE at a YAML registry (it takes precedence over the single-instance env vars). Values may reference environment variables with ${VAR}: