You run an MCP server that provides safe, focused access to Airflow data in JSON form. This server lets you inspect DAGs, runs, and logs, with optional write operations gated by client approval. Use it from your MCP client to query Airflow instances you configure, get structured results, and trace requests with a unique identifier.

How to use

Use an MCP client to call the server’s tools by name with JSON arguments. You can connect via HTTP for tooling and automation, or via STDIO for interactive workflows in a terminal.

How to install

Prerequisites you need before starting: Node.js toolchain for UVU-based commands or Python for pip-based installations.

Step 1: Install the MCP server via the Python package distributor.

uv tool install apache-airflow-mcp-server

# If you don’t have uv installed, fall back to pip
pip install apache-airflow-mcp-server

Configuration and startup

Prepare an instances registry in YAML that lists all Airflow endpoints you will access. You can reference environment variables in the values. Provide a data channel for each Airflow deployment you manage.

# Example (`examples/instances.yaml`):
# Data team staging instance
data-stg:
  host: https://airflow.data-stg.example.com/
  api_version: v1
  verify_ssl: true
  auth:
    type: basic
    username: ${AIRFLOW_INSTANCE_DATA_STG_USERNAME}
    password: ${AIRFLOW_INSTANCE_DATA_STG_PASSWORD}

# ML team staging instance
ml-stg:
  host: https://airflow.ml-stg.example.com/
  api_version: v1
  verify_ssl: true
  auth:
    type: basic
    username: ${AIRFLOW_INSTANCE_ML_STG_USERNAME}
    password: ${AIRFLOW_INSTANCE_ML_STG_PASSWORD}

# Bearer token (experimental)
# ml-prod:
#   host: https://airflow.ml-prod.example.com/
#   api_version: v1
#   verify_ssl: true
#   auth:
#     type: bearer
#     token: ${AIRFLOW_INSTANCE_ML_PROD_TOKEN}

Run the server

Start the server in HTTP mode for tooling. You will listen on a host and port you choose.

uv run airflow-mcp --transport http --host 127.0.0.1 --port 8765

For STDIO based workflows (CLI/terminal)

uv run airflow-mcp --transport stdio

## Health and discovery

Check liveness over HTTP. A healthy server responds with 200 OK on the health endpoint.

Optional discovery payloads are available for tooling that auto-discovers endpoints.

## Available tools

### airflow\_list\_instances

Discover configured instance keys and the default instance.

### airflow\_describe\_instance

Return host, API version, verify\_ssl, and redacted authentication type for an instance.

### airflow\_resolve\_url

Resolve instance and identifiers from an Airflow UI URL.

### airflow\_list\_dags

List compact DAGs with UI links, filtered by state or other criteria.

### airflow\_get\_dag

Fetch DAG details plus UI link.

### airflow\_list\_dag\_runs

List DAG runs with UI links and optional filters; supports ordering.

### airflow\_get\_dag\_run

Get details for a specific DAG run and its UI link.

### airflow\_list\_task\_instances

List task instances for a run with per-attempt links and optional filters.

### airflow\_get\_task\_instance

Get concise task metadata with optional rendered fields and UI links.

### airflow\_get\_task\_instance\_logs

Fetch task logs with server-side filtering and context options.

### airflow\_dataset\_events

List dataset events if supported by the Airflow deployment.

### airflow\_trigger\_dag

Trigger a DAG run with optional configuration and notes (write action).

### airflow\_clear\_task\_instances

Clear a set of task instances with optional date range and dry-run mode (write action).

### airflow\_clear\_dag\_run

Clear a specific DAG run with optional flags (write action).

### airflow\_pause\_dag

Pause a DAG to suspend scheduling (write action).

### airflow\_unpause\_dag

Unpause a paused DAG (write action).