Overview

This MCP (Model Context Protocol) server exposes an Airflow cluster’s REST API as a set of natural-language “tools” that language models and agent frameworks can call. Instead of embedding direct HTTP calls into an LLM prompt, the MCP server translates common Airflow operations (list DAGs, trigger runs, inspect task instances, fetch logs, manage variables/connections) into tool descriptors and endpoints that follow the MCP pattern. This makes it straightforward to integrate Airflow control into LLM agents, copilots, and automated incident responders while keeping credentials and API logic centralized.

By converting Airflow operations into language-friendly tools, the server lowers the friction for building automation workflows. Developers can let an LLM request a high-level action (for example, “restart the most recent failed DAG run for dag_id X”) and the agent will call the appropriate MCP tool. The server handles request validation, authentication to the Airflow API, and maps natural parameters into Airflow API calls.

Features

Wraps Airflow REST API endpoints as MCP-compatible tools
Tool metadata (name, description, parameters) exposed for LLM tool discovery
Common Airflow operations: list DAGs, trigger DAG runs, get run status, task instance inspection, fetch logs, manage variables and connections
Authentication support via environment variables or Airflow API tokens
Configurable request timeouts, rate limits, and CORS
Optional Docker deployment for easy hosting
Logging and basic telemetry for request auditing

Installation / Configuration

Prerequisites: Python 3.9+, pip, access to an Airflow REST API endpoint.

Quick start (clone, virtualenv, run):

git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# export basic configuration
export AIRFLOW_API_BASE_URL="https://airflow.example.com/api/v1"
export AIRFLOW_USERNAME="admin"
export AIRFLOW_PASSWORD="secret"
export MCP_SERVER_HOST="0.0.0.0"
export MCP_SERVER_PORT="8080"

# run the MCP server
python -m mcp_airflow_api.server

Docker (example):

# docker-compose.yml
version: "3.8"
services:
  mcp-airflow:
    image: ghcr.io/call518/mcp-airflow-api:latest
    environment:
      - AIRFLOW_API_BASE_URL=https://airflow.example.com/api/v1
      - AIRFLOW_USERNAME=admin
      - AIRFLOW_PASSWORD=secret
      - MCP_SERVER_PORT=8080
    ports:
      - "8080:8080"

Configuration options (common environment variables):

AIRFLOW_API_BASE_URL: Base URL for Airflow REST API
AIRFLOW_USERNAME / AIRFLOW_PASSWORD: Basic auth credentials (or use AIRFLOW_API_TOKEN)
MCP_SERVER_HOST / MCP_SERVER_PORT: Binding for MCP server
MCP_REQUEST_TIMEOUT: Timeout (seconds) for proxied requests
MCP_ALLOWED_ORIGINS: CORS origins (comma-separated)

Available Tools

The server exposes a set of tools that map to Airflow functionality. Names and parameters are discoverable via the MCP tools endpoint (e.g., GET /mcp/tools). Common tools include:

Tool name	Description	Key parameters
list_dags	Return DAG metadata and status	limit, offset, tags
get_dag	Fetch a DAG by dag_id	dag_id
trigger_dag_run	Create a DAG run	dag_id, conf, run_id
get_dag_run	Inspect a DAG run	dag_id, dag_run_id
list_task_instances	List task instances for a run	dag_id, dag_run_id
get_task_log	Fetch logs for a task instance	dag_id, dag_run_id, task_id, try_number
set_variable	Create/update Airflow variable	key, value
get_variable	Read Airflow variable	key
pause_dag / unpause_dag	Pause or unpause a DAG	dag_id

Tool descriptors include human-readable descriptions and JSON-schema-like parameter definitions to help LLMs construct valid calls.

Example: fetch tools metadata

curl -sS http://localhost:8080/mcp/tools | jq .

Use Cases

Automated incident response: An LLM agent inspects failed DAG runs, fetches task logs, and suggests or executes retries or fixes (trigger runs, clear task instances).
- Example flow: list_dags -> get_dag_run (status=failed) -> get_task_log -> trigger_dag_run
ChatOps for data engineers: Allow engineers to ask a bot “Show me the last run for dag_id X” or “Pause DAG Y for maintenance” and have the bot call MCP tools rather than raw Airflow API.
- Example command via agent: get_dag_run(dag_id=“data_pipeline”, dag_run_id=“scheduled__2026-04-08T00:00:00”)
Audited automation: Centralize Airflow operations through the MCP server to capture request logs, enforce rate limits, and apply consistent authentication rather than distributing credentials to multiple agents.
Integration into LLM-driven orchestration: Combine MCP Airflow tools with other MCP servers (cloud, database, monitoring) so a single agent can triage issues end-to-end (e.g., detect failed runs, query metrics, and scale resources).

Tips and Next Steps

Mount a secrets manager or use environment-specific tokens to avoid embedding credentials in code.
Use the tools endpoint for discovery before composing calls — LLMs work best when they receive parameter schemas.
Consider adding custom tool wrappers for organization-specific workflows (e.g., clear & re-run patterns, parameterized DAG templates).

Repository and source code: https://github.com/call518/MCP-Airflow-API

MCP Server for Airflow API LLM Integration