Airflow MCP

A Model Context Protocol server that exposes Apache Airflow's REST API to AI agents (Claude Code, Claude Desktop, etc.), so they can inspect and operate on DAGs, DAG runs, task instances and logs.

The server is general-purpose: point it at any Airflow 2.x/3.x instance via AIRFLOW_BASE_URL. It has no knowledge of any specific project's DAGs, and does not edit DAG files or manage Airflow users/roles/pools/connections.

Tools

Read-only

Tool	Description	Parameters
`list_dags`	List DAGs, optionally filtered by tag or active state	`tags?`, `only_active?`, `limit?`, `offset?`
`get_dag`	Get metadata for a single DAG	`dag_id`
`list_dag_runs`	List DAG run history	`dag_id`, `state?`, `limit?`
`get_dag_run`	Get details for a single DAG run, including trigger conf	`dag_id`, `dag_run_id`
`list_task_instances`	List task instances and their state for a DAG run	`dag_id`, `dag_run_id`
`get_task_logs`	Get logs for a task instance, truncated to `AIRFLOW_LOG_MAX_LINES`	`dag_id`, `dag_run_id`, `task_id`, `try_number?`

Write (sensitive — annotated so MCP clients require confirmation)

Tool	Description	Parameters
`trigger_dag_run`	Trigger a new DAG run (destructive, non-idempotent)	`dag_id`, `conf?`, `logical_date?`
`pause_dag`	Pause a DAG (idempotent)	`dag_id`
`unpause_dag`	Resume a paused DAG (idempotent)	`dag_id`

Requirements

Python >= 3.12
uv
An Apache Airflow instance reachable over HTTP, with a user that has at least Viewer role (Op if you need the write tools)

Least privilege

Use a dedicated Airflow user for this server, scoped to the minimum role it needs:

Viewer is enough if you only register the read-only tools.
Op is required if you also register trigger_dag_run, pause_dag or unpause_dag.
Never point this server at an Admin account unless you have a specific reason to.

Quickstart

./install.sh

Detects whether you have Docker or uv installed, sets up .env (from .env.example, if missing), builds the image or syncs dependencies accordingly, and prints the .mcp.json snippet to register the server.

Setup

uv sync --group dev
cp .env.example .env

Fill in .env with your Airflow instance's URL and credentials.

Docker

No local Python/uv needed — build once, run anywhere Docker runs:

docker build -t mcp-airflow .
cp .env.example .env  # fill in your Airflow credentials

Run in stdio mode (default, for MCP clients that spawn the process):

docker run -i --rm --env-file .env mcp-airflow

Run in streamable-http mode (standalone service, listens on :8000):

docker run --rm -p 8000:8000 --env-file .env -e MCP_TRANSPORT=streamable-http mcp-airflow

Registering with an MCP client

stdio (recommended for local development)

{
  "mcpServers": {
    "airflow": {
      "command": "uv",
      "args": ["run", "mcp-airflow"],
      "env": {
        "AIRFLOW_BASE_URL": "http://localhost:8080",
        "AIRFLOW_AUTH_MODE": "basic",
        "AIRFLOW_USERNAME": "airflow",
        "AIRFLOW_PASSWORD": "airflow"
      }
    }
  }
}

stdio via Docker

{
  "mcpServers": {
    "airflow": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", ".env", "mcp-airflow"]
    }
  }
}

streamable-http (server running as a standalone process)

Start the server with MCP_TRANSPORT=streamable-http uv run mcp-airflow (or the Docker command above), then register:

{
  "mcpServers": {
    "airflow": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Development

uv run pytest
uv run ruff check .
uv run mypy src