This server lets an AI coding assistant drive a development or local Apache Airflow cluster through Airflow's REST API, enabling the full write-a-DAG / run-it / read-the-logs development loop.
DAG Management
list_dags — List registered DAGs with their paused/active/import-error flags, file locations, tags, and scheduling info; filter by pattern or tags
set_dag_paused — Pause or unpause a DAG (new local DAGs start paused by default, blocking execution)
get_import_errors — Retrieve DAG parse failures with filenames and full tracebacks — the primary tool for diagnosing why a new DAG isn't showing up
DAG Run Operations
trigger_dag — Manually start a DAG run, optionally with a conf payload, logical date, and a note; returns the dag_run_id
list_dag_runs — List recent runs for a given DAG or across all DAGs, filterable by state
get_run_status — Get the state of a DAG run plus per-task states (task ID, state, try number, operator, timing, duration)
Task Operations
get_task_logs — Fetch logs for a specific task instance attempt, with try_number, map_index, and tail_lines options
clear_task_instances — Clear task instances for re-execution after a fix; supports dry-run preview, scoped clearing, and resetting DAG run state
Configuration Inspection (Read-Only)
list_variables — Read Airflow Variables (sensitive values masked; no create/modify)
list_connections — Read Airflow Connection metadata (passwords never returned; no create/modify)
Supports both Airflow 3 (default) and Airflow 2 via configurable API prefix and auth mode.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@airflow-dev-mcp Trigger the my_etl DAG and check its status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is an MCP server for driving a local or development Airflow cluster from an AI coding assistant such as Claude Code, Cursor, or any other MCP client. Use it to trigger DAG runs, watch their status, read task logs, and see why a DAG failed to parse, all without leaving your editor.
The server talks to Airflow through its REST API and nothing else. It never touches your
DAG source, filesystem, or database, and there are no config files to manage; everything
is set with environment variables. Both Airflow 3 (/api/v2) and Airflow 2 (/api/v1)
work, and the version is detected automatically.
The quickest way is claude mcp add, run from your project directory:
claude mcp add airflow-dev \
-e AIRFLOW_URL=http://localhost:8080 \
-e AIRFLOW_USERNAME=admin \
-e AIRFLOW_PASSWORD=admin \
-- uvx airflow-dev-mcpAdd --scope user to make it available in every project, or --scope project to write a
.mcp.json you can commit for your team. The default scope is local to you in the current
project.
To set it up by hand instead, put the following in a .mcp.json file at your project root:
{
"mcpServers": {
"airflow-dev": {
"command": "uvx",
"args": ["airflow-dev-mcp"],
"env": {
"AIRFLOW_URL": "http://localhost:8080",
"AIRFLOW_USERNAME": "admin",
"AIRFLOW_PASSWORD": "admin"
}
}
}
}For a setup that applies everywhere, put the same mcpServers block in ~/.claude.json.
Any client that launches stdio MCP servers works the same way. Have it run
uvx airflow-dev-mcp (or airflow-dev-mcp if you installed it) with the environment
variables below.
Related MCP server: Apache Airflow MCP Server
Variable | Default | Description |
|
| Base URL of the cluster, with no path. |
| — | Username, used together with |
| — | Password. |
|
| HTTP timeout, in seconds. |
|
| Set to |
Set AIRFLOW_USERNAME and AIRFLOW_PASSWORD and you are done; the server works out
whether it is talking to Airflow 3 or Airflow 2 on first use and authenticates the right
way.
Tool | What it does |
| List registered DAGs with their paused, active, and import-error flags. |
| Show parse failures with filename and traceback, so you can see why a new DAG isn't showing up. |
| Pause or unpause a DAG. New local DAGs start paused. |
| Start a manual DAG run, optionally with a |
| Report a run's state and its per-task states (task, state, try number, operator, timing). |
| Return the logs for one task attempt, tailed to the last N lines by default. |
| List recent runs of a DAG, to find a run when you don't have its id. |
| Clear tasks so they re-run. Previews as a dry run by default. |
| Read Airflow Variables. |
| Read Airflow Connections, with passwords omitted. |
Only trigger_dag, set_dag_paused, and clear_task_instances change anything on the
cluster; everything else is read-only. There are no tools that create or modify Variables
or Connections.
MIT, see LICENSE.
If you are interested in contributing see: CONTRIBUTING.md.
Clear task instances so they re-run — the fast way to re-test a task after a fix.
Defaults to a DRY RUN: it reports which task instances would be cleared without touching them. Pass dry_run=False to actually clear; with reset_dag_runs=True the affected run is put back into a running state so cleared tasks re-execute.
Args: dag_id: DAG identifier. dag_run_id: Restrict to a single run (recommended). If omitted, the API's other filters apply across runs. task_ids: Restrict to specific task_ids. If omitted, all matching tasks are cleared. only_failed: When True, only clear failed task instances. reset_dag_runs: When True (default), set affected runs back to running so cleared tasks are re-scheduled. dry_run: When True (default), preview only. Set False to actually clear.
Returns:
ClearResult with dry_run (echoed) and task_instances (the affected TIs).
Inputs: dag_id (required), dry_run, task_ids, dag_run_id, +2 more. Returns: Result of a clearTaskInstances call.
List DAG import errors (parse failures) recorded by the scheduler.
The primary debugging tool when a DAG you just wrote isn't showing up: a file that raises at import time is recorded here with its filename and full traceback.
Args: limit: Max errors to return (default 100). offset: Pagination offset.
Returns:
ImportErrorList with import_errors (filename, stack_trace, timestamp,
import_error_id) and total_entries.
Inputs: limit, offset. Returns: import_errors, total_entries
Get the state of a DAG run and (optionally) its task instances.
Args:
dag_id: DAG identifier.
run_id: DAG run identifier returned by trigger_dag
(e.g. manual__2026-07-02T14:23:11+00:00).
include_tasks: When True (default), also fetch per-task states.
Returns:
RunStatus with run (a DagRunSummary) and, if requested, tasks (a list of
TaskInstanceSummary: task_id, state, try_number, operator, start/end dates,
duration, map_index). tasks is null when include_tasks is False.
Inputs: dag_id (required), run_id (required), include_tasks. Returns: A DAG run plus, optionally, its task instances.
Fetch logs for a single task instance attempt.
Args:
dag_id: DAG identifier.
run_id: DAG run identifier.
task_id: Task identifier within the DAG.
try_number: Attempt number (1-indexed). Retried tasks have multiple attempts —
call get_run_status to see the latest try_number per task.
map_index: Mapped task index for dynamic task mapping. Use -1 for a normal task.
tail_lines: Return only the last N lines (default 500). Pass null for the full log —
beware, large tasks can produce many MB of output that will blow up context.
Returns:
TaskLogResult with content (log text), truncated (True if tailing dropped earlier
lines), line_count (lines returned), and try_number (echoed back).
Inputs: dag_id (required), run_id (required), task_id (required), map_index, +2 more. Returns: Logs for one task instance attempt.
List Airflow Connections (read-only) — passwords are never returned by the API.
Read-only by design: use it to confirm a connection exists with the expected conn_type / host / schema when a task fails to connect.
Args: limit: Max connections to return (default 100). offset: Pagination offset.
Returns:
ConnectionList with connections (connection_id, conn_type, host, db_schema,
login, port, description) and total_entries.
Inputs: limit, offset. Returns: connections, total_entries
List recent runs of a DAG — useful when you don't already hold a run_id.
Args: dag_id: DAG identifier. Pass "~" to list runs across all DAGs. limit: Max runs to return (default 25). offset: Pagination offset. state: Optional filter, e.g. ["running"], ["failed"], ["success", "queued"].
Returns:
DagRunList with dag_runs (each a DagRunSummary) and total_entries.
Inputs: dag_id (required), limit, state, offset. Returns: dag_runs, total_entries
List DAGs registered in the cluster with their paused / import-error flags.
Use this to confirm a DAG parsed and registered. Important: a DAG whose file fails
to import at module load does NOT appear here at all — call get_import_errors for that.
Args: limit: Max DAGs to return (default 100). offset: Pagination offset. dag_id_pattern: Optional case-insensitive substring filter on dag_id. tags: Optional list of tags; only DAGs carrying one of them are returned.
Returns:
DagList with dags (dag_id, is_paused, is_active, has_import_errors, fileloc,
description, tags, next_dagrun, last_parsed_time) and total_entries.
Inputs: tags, limit, offset, dag_id_pattern. Returns: dags, total_entries
List Airflow Variables (read-only) — handy when troubleshooting why a task can't find config it expects.
Values flagged sensitive by Airflow's secrets masker come back masked. Read-only by design: this tool cannot create or modify variables.
Args: limit: Max variables to return (default 100). offset: Pagination offset.
Returns:
VariableList with variables (key, value, description) and total_entries.
Inputs: limit, offset. Returns: variables, total_entries
Pause or unpause a DAG.
Locally, newly added DAGs are paused by default, so trigger_dag will queue a run
that never executes until the DAG is unpaused. Call this with paused=False to enable it.
Args: dag_id: DAG identifier. paused: True to pause, False to unpause.
Returns: DagInfo reflecting the updated state.
Inputs: dag_id (required), paused (required). Returns: Registration-level view of a DAG (not a specific run).
Trigger a manual run of a DAG in the dev Airflow cluster.
Args:
dag_id: DAG identifier as it appears in Airflow.
conf: Optional dict passed to the run (accessible as dag_run.conf inside tasks).
logical_date: Optional ISO-8601 timestamp for the run's logical date. Defaults to now.
note: Optional human-readable note attached to the run.
Returns:
DagRunSummary for the created run, including dag_run_id needed for status/log lookups.
Note: if the DAG is paused, the run is created in queued state but will not execute
until the DAG is unpaused (see set_dag_paused).
Inputs: dag_id (required), conf, note, logical_date. Returns: Condensed view of an Airflow DAG run. The aliases absorb the AF2/AF3 naming dif…
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool targets a distinct resource or action with no overlap: clearing tasks, listing import errors, checking run status, fetching logs, listing connections/dag runs/DAGs/variables, toggling pause, and triggering runs. An agent can easily distinguish between them.
All tool names follow a consistent verb_noun pattern with lowercase underscores (e.g., clear_task_instances, get_import_errors, list_dags). Although verbs vary (clear, get, list, set, trigger), the pattern is uniform and predictable.
10 tools is well-scoped for an Airflow dev MCP server. It covers essential operations without being bloated or insufficient, providing a focused set for common development tasks.
The tool surface covers the main workflows: triggering, monitoring, logging, pausing, and basic asset listing. A minor gap is the lack of a dedicated get_dag endpoint, but list_dags with filtering partially compensates. No CRUD on connections/variables is acceptable for a read-only dev environment.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
