About airflow
@us-all/airflow-mcp is an MCP server for operating Airflow 3.x through its REST API. It provides read-focused DAG, run, task, and log access, while write actions require an explicit environment-variable gate.
Key features
- 01List DAGs and recent runs
- 02Inspect task instances and logs
- 03Aggregate DAG health metrics
- 04Trigger runs and clear tasks with write gate
- 05JWT authentication and token refresh
Use cases
- 01Investigate failed DAG runs
- 02Review DAG success rates and durations
- 03Trigger or rerun tasks when writes are enabled
MCP support
The server exposes Airflow REST API operations as MCP tools and includes two DAG triage prompts. It uses stdio by default, with optional Streamable HTTP transport.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @us-all/airflow-mcpAIRFLOW_API_URLAirflow host base, e.g. 'http://airflow.example.com:8080'. Server prepends /api/v2 internally; trailing /api/v1 or /api/v2 is stripped if supplied.AIRFLOW_USERNAMEAirflow username (used to mint a JWT via SimpleAuthManager /auth/token).AIRFLOW_PASSWORDSecretAirflow password (used to mint a JWT via SimpleAuthManager /auth/token).AIRFLOW_ALLOW_WRITESet to 'true' to enable trigger-dag and clear-task tools. Default read-only.AIRFLOW_TOOLSComma-separated category allowlist (airflow,meta).AIRFLOW_DISABLEComma-separated category disablelist.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
17Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| tag | string | No | Filter to DAGs that carry this tag |
| limit | integer | No | |
| search | string | No | Substring match on dag_id (case-insensitive) |
| onlyActive | boolean | No | Filter out paused DAGs (Airflow 3.x: is_paused=false) |
| extractFields | string | No | Comma-separated dotted paths to project from response (e.g. 'id,name,owner.name,columns.*.name'). Use `*` as wildcard for arrays/objects. Wrap field names with dots in backticks. Reduces response tokens dramatically on large entities. |
Details
From the project README@us-all/airflow-mcp
Airflow MCP server — read DAGs, runs, task instances, log tails; trigger and clear (write-gated). Built on
@us-all/mcp-toolkit.
A focused MCP for the Airflow 3.x REST API (/api/v2). Read by default; airflow-trigger-dag and airflow-clear-task are gated behind AIRFLOW_ALLOW_WRITE=true. Auth is JWT via SimpleAuthManager — supply AIRFLOW_USERNAME + AIRFLOW_PASSWORD and the server mints/refreshes the token transparently.
For deeper dbt integration (manifest parsing, run-results history, source freshness, per-column test coverage, lineage walks, custom DQ result tables), install the companion @us-all/dbt-mcp alongside.
- 7 tools in
airflow+metacategories - 2 MCP Prompts for DAG triage workflows
- 1 aggregation tool that replaces the list-runs → get-task-instances combo
Install
pnpm add -D @us-all/airflow-mcp
Run
AIRFLOW_API_URL=http://airflow.example.com:8080 \
AIRFLOW_USERNAME=admin AIRFLOW_PASSWORD=... \
npx @us-all/airflow-mcp
Pass the host base only — the server prepends /api/v2 internally. A trailing /api/v1 or /api/v2 is stripped if supplied. JWT tokens are cached for the lifetime of the session and refreshed 1 minute before they expire.
The server speaks MCP stdio; wire it into Claude Desktop / Cursor / any MCP client. Set MCP_TRANSPORT=http to opt in to Streamable HTTP transport (Bearer auth, /health endpoint).
Tools
airflow (6 + 1 aggregation)
| Tool | Description |
|---|---|
airflow-list-dags | List active DAGs with tag/search filters |
airflow-list-runs | Recent runs of one DAG (state filter, ordered newest first) |
airflow-get-task-instances | Task instances for a specific DAG run |
airflow-get-task-logs | Tail (last N kB) of one task instance log |
airflow-trigger-dag | Trigger a new run (write-gated) |
airflow-clear-task | Clear specific task instances → re-run (write-gated) |
dag-health-rollup | Aggregated DAG health: success rate + avg duration + last failed run + failing tasks |
meta
search-tools — natural-language tool discovery.
Prompts
| Prompt | Use when |
|---|---|
dag-failure-triage | "Why did DAG X fail?" — pulls runs, isolates failure, dumps logs, proposes remediation |
dag-schedule-audit | "Sweep all DAGs for low success rate and stuck runs" |
Environment variables
| Env | Required | Notes |
|---|---|---|
AIRFLOW_API_URL | yes | Airflow host base, e.g. http://airflow.example.com:8080. Trailing /api/v1 or /api/v2 is stripped if present |
AIRFLOW_USERNAME | yes | Username for JWT minting via SimpleAuthManager /auth/token |
AIRFLOW_PASSWORD | yes | Password for JWT minting (secret) |
AIRFLOW_ALLOW_WRITE | no | true enables airflow-trigger-dag / airflow-clear-task |
AIRFLOW_TOOLS / AIRFLOW_DISABLE | no | Category toggles |
Tested-against schemas
- Airflow 3.0–3.2
/api/v2(verified against 3.2.1, current Airflow release as of 2026-05). Airflow 2.x is not supported by v0.2+ because basic auth +/api/v1were removed; pin to@us-all/[email protected]for Airflow 2.x deployments.
Companion server
For dbt artifact parsing, run-results history, and DQ result tables, install @us-all/dbt-mcp alongside.
Build
pnpm install
pnpm run build # tsc → dist/
pnpm test # vitest
pnpm run smoke # spawns dist/index.js, calls initialize + tools/list (set env first)
License
MIT — see LICENSE.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.