{
"markdown": "# Apache Airflow MCP Server\n\n\n\n[](https://modelcontextprotocol.io)\n[](https://pypi.org/project/apache-airflow-mcp-server/)\n[](https://pypi.org/project/apache-airflow-mcp-server/)\n[](https://airflow.apache.org/)\n[](https://github.com/madamak/apache-airflow-mcp-server/actions/workflows/ci.yml)\n[](https://github.com/madamak/apache-airflow-mcp-server/actions/workflows/security.yml)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/astral-sh/ruff)\n\n> Independent community project; not affiliated with or endorsed by the Apache Software Foundation.\n\nPublished through [PyPI](https://pypi.org/project/apache-airflow-mcp-server/),\n[GHCR](https://github.com/madamak/apache-airflow-mcp-server/pkgs/container/apache-airflow-mcp-server),\nand the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.madamak%2Fapache-airflow-mcp-server).\nReproducible scan reports, dependency audits, SBOMs, and provenance are attached\nto each [immutable release](https://github.com/madamak/apache-airflow-mcp-server/releases/latest).\n\nConnect Claude, Cursor, VS Code, or another [MCP](https://modelcontextprotocol.io) client to your Apache Airflow deployments and help agents diagnose failed DAGs.\n\nPaste 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.\n\n## Highlights\n\n- π **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)\n- π’ **Multi-instance** β one server for same-API-family dev/staging/prod targets, with per-instance credentials and an SSRF guard that rejects unknown hosts\n- π **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\n- π **Token-efficient** β log tailing, level filtering, byte caps, and truncation metadata designed for LLM context windows\n- π§ **Airflow 2 and 3** β API v1/v2 adapters with live E2E against Airflow 2.11 and 3.3, including JWT auth\n- π **Traceable** β every response carries a `request_id` that matches the structured server logs\n\n## Quickstart\n\n### 1. Install\n\n```bash\nuv tool install apache-airflow-mcp-server \\\n --with 'apache-airflow-client==3.3.0' # replace 3.3.0 with your Airflow version\n```\n\n> **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](#airflow-compatibility) before using a different release.\n\n### 2. Connect your MCP client\n\nThe fastest path is a single instance configured entirely with environment variables β no config file needed.\n\n\nClaude Code
\n\n```bash\nclaude mcp add airflow \\\n --env AIRFLOW_MCP_HOST=https://airflow.example.com \\\n --env AIRFLOW_MCP_USERNAME=admin \\\n --env AIRFLOW_MCP_PASSWORD=your-password \\\n --env AIRFLOW_MCP_READ_ONLY=true \\\n -- uvx --from apache-airflow-mcp-server \\\n --with apache-airflow-client==3.3.0 airflow-mcp --transport stdio\n```\n \n\n\nClaude Desktop
\n\nAdd to `claude_desktop_config.json` (Settings β Developer β Edit Config):\n\n```json\n{\n \"mcpServers\": {\n \"airflow\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"apache-airflow-mcp-server\", \"--with\", \"apache-airflow-client==3.3.0\", \"airflow-mcp\", \"--transport\", \"stdio\"],\n \"env\": {\n \"AIRFLOW_MCP_HOST\": \"https://airflow.example.com\",\n \"AIRFLOW_MCP_USERNAME\": \"admin\",\n \"AIRFLOW_MCP_PASSWORD\": \"your-password\",\n \"AIRFLOW_MCP_READ_ONLY\": \"true\"\n }\n }\n }\n}\n```\n \n\n\nCursor
\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"airflow\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"apache-airflow-mcp-server\", \"--with\", \"apache-airflow-client==3.3.0\", \"airflow-mcp\", \"--transport\", \"stdio\"],\n \"env\": {\n \"AIRFLOW_MCP_HOST\": \"https://airflow.example.com\",\n \"AIRFLOW_MCP_USERNAME\": \"admin\",\n \"AIRFLOW_MCP_PASSWORD\": \"your-password\",\n \"AIRFLOW_MCP_READ_ONLY\": \"true\"\n }\n }\n }\n}\n```\n \n\n\nVS Code (Copilot)
\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"airflow\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"apache-airflow-mcp-server\", \"--with\", \"apache-airflow-client==3.3.0\", \"airflow-mcp\", \"--transport\", \"stdio\"],\n \"env\": {\n \"AIRFLOW_MCP_HOST\": \"https://airflow.example.com\",\n \"AIRFLOW_MCP_USERNAME\": \"admin\",\n \"AIRFLOW_MCP_PASSWORD\": \"your-password\",\n \"AIRFLOW_MCP_READ_ONLY\": \"true\"\n }\n }\n }\n}\n```\n \n\n\nAny client, over HTTP
\n\nRun the server yourself and point the client at the endpoint:\n\n```bash\nAIRFLOW_MCP_HOST=https://airflow.example.com \\\nAIRFLOW_MCP_USERNAME=admin AIRFLOW_MCP_PASSWORD=your-password \\\nAIRFLOW_MCP_READ_ONLY=true \\\nairflow-mcp --transport http --host 127.0.0.1 --port 8765\n```\n\n```json\n{ \"mcpServers\": { \"airflow\": { \"url\": \"http://127.0.0.1:8765/mcp\" } } }\n```\n\nHealth check: `GET /health` β `200 OK`.\n \n\n### 3. Ask your agent something\n\n> *\"Why did the latest run of `etl_pipeline` fail?\"*\n>\n> *\"https://airflow.example.com/dags/etl_pipeline/grid β what happened here, and is it safe to clear?\"*\n>\n> *\"Show the failed task's error context and tell me the smallest recovery action.\"*\n\n## Airflow compatibility\n\nThe server talks to Airflow through the generated `apache-airflow-client`.\nFor Airflow 3, match the client release to your Airflow release: generated\nmodels can change within a major version, and a newer client is not guaranteed\nto deserialize an older server's responses correctly. Airflow 2.11 uses the\nfinal v1 client release, 2.10.0, against Airflow 2's stable API.\n\n| Your Airflow | REST API | Install | Live E2E status |\n|---|---|---|---|\n| 3.3 | v2 | `uv tool install apache-airflow-mcp-server --with 'apache-airflow-client==3.3.0'` | β
3.3.0 |\n| 2.11 | v1 | `uv tool install apache-airflow-mcp-server --with 'apache-airflow-client==2.10.0'` | β
Airflow 2.11 + final v1 client 2.10.0 |\n| 3.0β3.2 | v2 | Pin the client to the deployed Airflow 3 version | π§ͺ Not in the current live matrix |\n| 2.5β2.10 | v1 | Use the final v1 client, `apache-airflow-client==2.10.0` | π§ͺ Not in the current live matrix |\n\nWhen `api_version` isn't set, the server assumes the API matching the installed\nclient (`v1` for a 2.x client, `v2` for 3.x). Set\n`AIRFLOW_MCP_API_VERSION` (or `api_version:` in the registry) explicitly to\ncatch a major-version mismatch early.\n\nOne server process can currently load only one generated client major. All\ninstances in a registry must therefore use the same API family; run separate\nMCP server processes for Airflow 2 and Airflow 3. Mixed-version support requires\na future client-adapter change and is not advertised as working today.\n\nAirflow 3 notes:\n\n- **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).\n- `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.\n- 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.\n\nBoth client families are exercised on relevant pull requests and main pushes. Bug reports from real Airflow deployments are very welcome!\n\n## Configuration\n\n### Single instance (env vars only)\n\n| Variable | Required | Description |\n|---|---|---|\n| `AIRFLOW_MCP_HOST` | β
| Airflow base URL, e.g. `https://airflow.example.com` |\n| `AIRFLOW_MCP_USERNAME` / `AIRFLOW_MCP_PASSWORD` | β
* | Basic auth credentials |\n| `AIRFLOW_MCP_TOKEN` | β
* | Bearer/JWT token (used instead of basic auth) |\n| `AIRFLOW_MCP_API_VERSION` | | `v1` (Airflow 2) or `v2` (Airflow 3); defaults to whichever matches the installed `apache-airflow-client` |\n| `AIRFLOW_MCP_VERIFY_SSL` | | Verify TLS certificates (default `true`) |\n\n\\* provide either username+password or a token.\n\n### Multiple instances (registry YAML)\n\nPoint `AIRFLOW_MCP_INSTANCES_FILE` at a YAML registry (it takes precedence over the single-instance env vars). Values may reference environment variables with `${VAR}`:\n\n```yaml\ndata-stg:\n host: https://airflow.data-stg.example.com/\n api_version: v1 # Airflow 2\n verify_ssl: true\n auth:\n type: basic\n username: ${AIRFLOW_DATA_STG_USERNAME}\n password: ${AIRFLOW_DATA_STG_PASSWORD}\n\ndata-prod:\n host: https://airflow.data-prod.example.com/\n api_version: v1 # Keep one client/API family per server process\n auth:\n type: bearer\n token: ${AIRFLOW_DATA_PROD_TOKEN}\n```\n\nEvery tool accepts either an `instance` key (`data-stg`) or a `ui_url` β a full http(s) Airflow UI URL whose host is resolved against the registry, with unknown hosts rejected (SSRF guard). `ui_url` also auto-fills `dag_id`/`dag_run_id`/`task_id` when the link contains them. If both `instance` and `ui_url` are passed and disagree, the call fails with `INSTANCE_MISMATCH` rather than guessing.\n\n**Kubernetes tip:** mount the registry from a Secret at `/config/instances.yaml` and set `AIRFLOW_MCP_INSTANCES_FILE=/config/instances.yaml`.\n\n### Server options\n\n| Variable | Default | Description |\n|---|---|---|\n| `AIRFLOW_MCP_DEFAULT_INSTANCE` | | Default instance key (also names the env-var instance) |\n| `AIRFLOW_MCP_READ_ONLY` | `false` | Don't register write tools at all |\n| `AIRFLOW_MCP_HTTP_HOST` / `AIRFLOW_MCP_HTTP_PORT` | `127.0.0.1` / `8765` | HTTP transport bind |\n| `AIRFLOW_MCP_TIMEOUT_SECONDS` | `30` | Airflow API timeout |\n| `AIRFLOW_MCP_TOKEN_REFRESH_SECONDS` | `3600` | Airflow 3: JWT refresh interval for basic-auth instances |\n| `AIRFLOW_MCP_LOG_FILE` | | Optional log file path |\n| `AIRFLOW_MCP_ENABLE_EXTENDED_CLEAR_PARAMS` | `false` | Enable `include_*` clear params (Airflow β₯2.6) |\n| `AIRFLOW_MCP_HTTP_BLOCK_GET_ON_MCP` | `true` | Return 405 for `GET /mcp` (SSE reads) on HTTP deployments |\n\n### Read-only mode\n\nThe quickstarts set `AIRFLOW_MCP_READ_ONLY=true`: write tools (trigger, clear,\npause/unpause) are never registered. This prevents MCP mutations, but read tools\ncan still disclose sensitive logs, configuration, rendered fields, and DAG-run\ndata; use least-privilege Airflow credentials.\n\nTo enable recovery operations deliberately, set `AIRFLOW_MCP_READ_ONLY=false`.\nWrite tools then carry MCP `destructiveHint` annotations that clients can use\nwhen deciding whether to request confirmation. Annotations are advisory, so do\nnot enable writes unless the Airflow credentials and MCP client's approval\nbehavior are appropriate for the target environment.\n\n## Tools\n\n**Discovery & URL utilities**\n\n| Tool | Description |\n|---|---|\n| `airflow_list_instances` | List configured instance keys and the default |\n| `airflow_describe_instance` | Host, API version, auth type (secrets redacted) |\n| `airflow_resolve_url` | Parse an Airflow UI URL into instance + dag/run/task identifiers |\n\n**Read**\n\n| Tool | Description |\n|---|---|\n| `airflow_list_dags` | DAGs with pause state and UI links |\n| `airflow_get_dag` | DAG details |\n| `airflow_list_dag_runs` | Runs with state filters and ordering (latest first by default) |\n| `airflow_get_dag_run` | Single run details |\n| `airflow_list_task_instances` | Task attempts for a run; filter by `state` / `task_ids` server-side |\n| `airflow_get_task_instance` | Task metadata, retries, timings, optional rendered template fields |\n| `airflow_get_task_instance_logs` | Logs with level filtering, tailing, context lines, and byte caps |\n| `airflow_dataset_events` | Dataset (Airflow 2) / asset (Airflow 3) events |\n\n**Write** (annotated destructive so clients can require approval; hidden entirely in read-only mode)\n\n| Tool | Description |\n|---|---|\n| `airflow_trigger_dag` | Trigger a run with optional conf/logical date/note |\n| `airflow_clear_task_instances` | Clear task instances across runs (`dry_run=true` by default) |\n| `airflow_clear_dag_run` | Clear a whole run (`dry_run=true` by default) |\n| `airflow_pause_dag` / `airflow_unpause_dag` | Toggle DAG scheduling |\n\nEvery success payload includes a `request_id` for log correlation; failures raise a structured `ToolError` with `{code, message, request_id, context}`.\n\n## The incident workflow\n\nThis is the flow the tools were designed around β going from an alert link to a diagnosis in four calls:\n\n```python\n# 1. Alert contains an Airflow UI link β resolve it\nairflow_resolve_url(\"https://airflow.example.com/dags/etl_pipeline/grid?dag_run_id=...\")\n# β {instance, dag_id, dag_run_id, ...}\n\n# 2. Which tasks failed in this run?\nairflow_list_task_instances(dag_id=\"etl_pipeline\", dag_run_id=\"scheduled__2026-01-01\",\n state=[\"failed\"])\n\n# 3. Get attempt metadata (authoritative try_number, retries, timings)\nti = airflow_get_task_instance(dag_id=\"etl_pipeline\",\n dag_run_id=\"scheduled__2026-01-01\",\n task_id=\"transform_data\")\n\n# 4. Pull only the error lines, with context, capped for the LLM\nairflow_get_task_instance_logs(dag_id=\"etl_pipeline\",\n dag_run_id=\"scheduled__2026-01-01\",\n task_id=\"transform_data\",\n try_number=ti[\"attempts\"][\"try_number\"],\n tail_lines=500, filter_level=\"error\", context_lines=5)\n```\n\nLog responses include `truncated`, `auto_tailed` (logs >100MB tail automatically), `match_count`, and byte/line stats so the agent knows exactly what it's looking at. Host-segmented logs are flattened with `--- [worker-1] ---` headers; Airflow 3 structured logs are rendered as plain lines.\n\n> **Note on `try_number`:** reschedule-mode sensors could increment it on every\n> reschedule through Airflow 2.9; Airflow 2.10+ no longer does. Always read it\n> from `airflow_get_task_instance` rather than guessingβthe derived\n> `retries_consumed`/`retries_remaining` fields are heuristics.\n\n## Deployment\n\n### Docker\n\n```bash\ndocker run -p 127.0.0.1:8765:8765 \\\n -e AIRFLOW_MCP_HOST=https://airflow.example.com \\\n -e AIRFLOW_MCP_USERNAME=admin \\\n -e AIRFLOW_MCP_PASSWORD=your-password \\\n -e AIRFLOW_MCP_READ_ONLY=true \\\n ghcr.io/madamak/apache-airflow-mcp-server:latest\n```\n\nOr build locally with `docker build -t airflow-mcp .`\n\nThe release image contains the lockfile's Airflow 3.3 client and serves\nstreamable HTTP on `:8765` (`/mcp` endpoint, `/health` for probes). The MCP HTTP\nendpoint has no built-in caller authentication: keep it loopback-bound or place\nit behind an authenticated private proxy. Mount a same-API-family registry YAML\nfor multi-instance setups. Airflow 2 deployments should use the pinned local\ninstallation path above until a separate v1 image is published.\n\nCI audits the exact image's installed Python dependencies and scans both the\nread-only and write-enabled MCP tool surfaces with a pinned Cisco MCP Scanner\nrelease's YARA analyzer. The security workflow fails on incomplete scans or any\nuntriaged YARA finding. Starting with v1.0.1, release assets include the\nmachine-readable scan reports, and release image manifests carry attached SBOM\nand provenance attestations covering their broader package inventory. These\nare automated checks, not a security certification or substitute for\ndeployment-specific review.\n\n### FastMCP tooling\n\nA `fastmcp.json` is included so FastMCP-aware tooling can auto-discover the entrypoint and deployment defaults.\n\n## Development\n\n```bash\nuv sync # install dependencies\nuv run pytest # unit tests (no real network; the Airflow client is mocked)\nuv run ruff check . # lint\nuv run ruff format . # format\nuv run airflow-mcp --transport stdio # run locally\n./scripts/e2e.sh af2 # end-to-end against Airflow 2.11\n./scripts/e2e.sh af3 # end-to-end against Airflow 3.3\n # Both seed failures/noisy logs and drive every tool\n # through MCP. Set E2E_KEEP=1 to keep the instance up.\n```\n\nCI runs the unit suite against both `apache-airflow-client` families on Python 3.10β3.13. Relevant pull requests, main pushes, nightly runs, and releases also exercise live dockerized Airflow 2.11 and 3.3. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [AGENTS.md](AGENTS.md) if you're pointing a coding agent at this repo (it's written for that).\n\n## Contributing\n\nIssues and PRs are welcome β especially:\n\n- Reports from real Airflow incident-response workflows and version combinations\n- Bounded-log, diagnosis-safety, and URL-first workflow improvements\n- Client setup recipes for more MCP hosts and deployment types\n\nIf this server saves you a debugging session, a β helps other Airflow teams find it.\n\n## License\n\nApache 2.0 β see [LICENSE](LICENSE).\n\nApache Airflow and Airflow are registered trademarks of The Apache Software Foundation. This independent project is not affiliated with or endorsed by the ASF.\n",
"bytes": 18555,
"sha": "edaa2afe268af32f9efc841798864afe29aa28ca16372d4a1b06b581a14ea30b",
"repo_slug": "madamak/apache-airflow-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_madamak_apache_airflow_mcp_ser_78cd297b/readme"
}