Skip to main content
Glama

airflow-mcp

A local Model Context Protocol server for inspecting and managing Apache Airflow 3. List DAGs and tasks, investigate runs, pause scheduling, retry work in an existing run, and manage connections without returning credentials to the model.

Read-only by default. Mutation and privileged connection-export tools require explicit startup flags. Tested against Airflow 3.3.1. This is an independent project, not an Apache Software Foundation project.

Quick start

Requires Python 3.11+, Git, and an Airflow API identity. Configure a local MCP client to launch:

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ErikBPF/airflow-mcp", "airflow-mcp"],
      "env": {
        "AIRFLOW_URL": "https://airflow.example.com",
        "AIRFLOW_TOKEN": "<supply through your client's secret configuration>"
      }
    }
  }
}

Pin a reviewed commit in the Git URL for repeatable installations. No PyPI release is claimed. Never commit a real token in client configuration. Alternatively, set AIRFLOW_AUTH_FILE to an absolute path to a mode 0600, gitignored, untracked *.secrets.json file containing either token or username and password. See authentication.

For a checkout:

uv sync --locked
uv run airflow-mcp

Transport is stdio only. The client starts the process locally; there is no network MCP listener or hosted OAuth service. Airflow requests verify TLS and do not follow redirects. HTTP is allowed only for loopback addresses, for example through a secure tunnel.

Related MCP server: Apache Airflow MCP Server

Tools

Tool

Purpose

Availability

list_dags

Native API filters, sorting, pagination and DAG-ID regex

Default

list_tasks

DAG task definitions, sorting and task-ID regex

Default

list_task_instances

Execution state, timestamps, duration, pools, queues, attempts, mapped indexes and regex

Default

list_runs

Existing run inventory

Default

inspect_run

Task attempts and elapsed run time; explicitly reports truncation

Default

set_dag_paused

Pause/unpause scheduling

--allow-writes

restart_run

Preview or clear tasks plus downstream, or a full existing run

--allow-writes

fail_run

Mark an existing run failed

--allow-writes

edit_connection

Edit a database-managed connection from a local private JSON file

--allow-writes

test_connection

Test a stored connection from the API server

--allow-writes

export_connection

Export actual values through an operator-configured privileged helper

--allow-connection-export

No tool creates a new DAG run. Restart preserves its run ID and original DAG version; it defaults to preview (execute=false). Selected task IDs include downstream tasks. Omitting task IDs clears the full existing run, including successful tasks. Only terminal runs are accepted. A mapped task ID selects all its indexes.

Pause does not cancel running compute. Marking a run failed does not prove external jobs stopped. Retrying tasks can repeat data writes; assess task idempotency before execution.

Filters

All query parameters from the tested API's DAG and task-instance list endpoints are exposed: 29 DAG options and 52 task-instance options. Task definitions support order_by; state/time filters belong to task instances. Native filters retain their original names and defaults. Repeated values use arrays. Date filters use timezone-aware ISO 8601 strings with _gte, _gt, _lte, _lt bounds.

{
  "dag_id": "~",
  "dag_run_id": "~",
  "dag_id_regex": "^etl_",
  "task_id_regex": "^(extract|load)_.*$",
  "state": ["failed", "upstream_failed"],
  "start_date_gte": "2026-11-17T00:00:00Z",
  "limit": 20
}

Native *_pattern means case-insensitive substring matching; *_prefix_pattern means case-sensitive prefix matching. MCP's ID regex extensions use Python search, case-sensitive unless an inline flag such as (?i) is supplied. Native and regex filters combine using AND.

Regex scans at most 1,000 native-filtered candidates, then applies offset/limit to matches. Totals reflect matches, not the upstream page. Regex rejects cursor; use offset pagination. Patterns are capped at 512 characters and execute in a subprocess with a one-second timeout. With regex, limit=0 returns all matches within the scan bound. Without regex, native cursor pagination remains available. Listings are not transactional snapshots during concurrent updates.

Connection values

Airflow's REST responses mask passwords. This project does not disable that protection or pretend masked values are credentials. An optional administrator-configured helper can resolve actual values in the Airflow runtime and write them directly to a new local private file. The model receives only the file path and status. See connections for the privilege boundary and helper contract.

Development and verification

uv sync --locked
uv run python -m unittest discover -s tests -p 'test_*.py' -v
uv build

Sandbox validation uses synthetic fixtures. Unit tests cover filter forwarding, regex bounds, credential-file handling, authentication and tool exposure. Live MCP validation exercises run recovery, connection round-trips and timestamp boundaries. These results do not establish production RBAC or external-secret backend behavior.

See design references, contributing, and security. Licensed under Apache License 2.0.

Available Tools

5 tools
inspect_runA
Read-only

Snapshot an existing run, its task attempts and elapsed wall-clock time (not summed task time).

Inputs: dag_id (required), run_id (required).

list_dagsA
Read-only

List DAGs using Airflow 3.3.1 API filters, pagination and sorting.

*_pattern is case-insensitive substring matching; *_prefix_pattern is case-sensitive. Dates use ISO 8601 with timezone. Lists become repeated query parameters. Prefix order_by fields with '-' for descending order. Unset filters use API defaults. dag_id_regex adds Python regex search (inline flags supported), applied before offset/limit. Regex scans at most 1000 native-filtered candidates; limit=0 returns all matches.

Inputs: tags, limit, offset, owners, +26 more.

list_runsC
Read-only

List existing runs; never creates runs.

Inputs: dag_id (required), limit, offset.

list_task_instancesA
Read-only

List task executions with all Airflow 3.3.1 API query filters.

Use '~' for all DAGs or runs. Date filters are timezone-aware ISO 8601 strings. Lists use repeated query parameters; order_by accepts '-' for descending order. cursor='' starts cursor pagination; pass returned next_cursor for the next page. When cursor is supplied, Airflow ignores offset. Patterns match substrings; prefix patterns are case-sensitive. No rendered fields or XCom values are returned. ID regexes use Python search with inline flags and combine with native filters using AND. Regex scans at most 1000 candidates before offset/limit pagination, forbids cursor, and returns a filtered total. With regex, limit=0 returns all matches.

Inputs: dag_id (required), dag_run_id (required), pool, limit, +52 more.

list_tasksA
Read-only

List task definitions in a DAG. This API supports order_by only (default task_id).

For state, duration, queue, pool or attempt filters, use list_task_instances. task_id_regex adds Python regex search over actual IDs, with a 1000-candidate cap.

Inputs: dag_id (required), order_by, task_id_regex.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation4/5

    The five tools mostly target distinct resources: DAGs, tasks, runs, a run snapshot, and task instances. The only mild overlap is between inspect_run's task attempts and list_task_instances, but the descriptions make the run-level vs execution-level distinction reasonably clear.

    Naming Consistency5/5

    All tool names use snake_case with a clear verb_noun pattern: list_runs, inspect_run, list_dags, list_tasks, and list_task_instances. The single inspect_ prefix variation is natural and does not break consistency.

    Tool Count5/5

    Five tools is a well-scoped set for a read-oriented Airflow inspection server. Each tool covers a distinct listing or inspection need without redundant operations.

    Completeness3/5

    The server covers broad listing and run snapshot inspection, but it lacks key follow-up operations such as getting a single DAG or task instance, retrieving logs, or accessing XCom values. These gaps will limit agents trying to debug task failures beyond enumeration.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables management of Amazon Managed Workflows for Apache Airflow (MWAA) environments and operations including DAG management, workflow execution monitoring, and access to Airflow connections and variables through a unified interface.
      21
      3
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables inspection and management of Apache Airflow DAGs, runs, and logs across multiple instances. It provides tools for monitoring workflows and performing gated write operations like triggering DAGs or clearing task instances.
      16
      73 PyPI
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only monitoring of Apache Airflow DAGs, including listing active DAGs, fetching recent runs, and analyzing execution history and performance metrics.
      1
      MIT