airflow-dev-mcp

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.

Configuring your MCP client

Claude Code

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-mcp

Add --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.

Manual configuration

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.

Other clients

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.

Configuration

Variable	Default	Description
AIRFLOW_URL	http://localhost:8080	Base URL of the cluster, with no path.
AIRFLOW_USERNAME	—	Username, used together with AIRFLOW_PASSWORD.
AIRFLOW_PASSWORD	—	Password.
AIRFLOW_TIMEOUT	30	HTTP timeout, in seconds.
AIRFLOW_VERIFY_SSL	true	Set to false to skip TLS verification for self-signed dev certs.

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.

Tools

Tool	What it does
list_dags	List registered DAGs with their paused, active, and import-error flags.
get_import_errors	Show parse failures with filename and traceback, so you can see why a new DAG isn't showing up.
set_dag_paused	Pause or unpause a DAG. New local DAGs start paused.
trigger_dag	Start a manual DAG run, optionally with a conf payload. Returns the dag_run_id.
get_run_status	Report a run's state and its per-task states (task, state, try number, operator, timing).
get_task_logs	Return the logs for one task attempt, tailed to the last N lines by default.
list_dag_runs	List recent runs of a DAG, to find a run when you don't have its id.
clear_task_instances	Clear tasks so they re-run. Previews as a dry run by default.
list_variables	Read Airflow Variables.
list_connections	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.

License

MIT, see LICENSE.

Contributing

If you are interested in contributing see: CONTRIBUTING.md.