Airflow MCP Server

A Model Context Protocol (MCP) server for Apache Airflow that provides AI assistants with access to Airflow's REST API. Built with FastMCP.

Quickstart

IDEs

Add to your MCP settings (Cursor: ~/.cursor/mcp.json, VS Code: .vscode/mcp.json):

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["astro-airflow-mcp", "--transport", "stdio"]
    }
  }
}

CLI Tools

claude mcp add airflow -- uvx astro-airflow-mcp --transport stdio

gemini mcp add airflow -- uvx astro-airflow-mcp --transport stdio

codex mcp add airflow -- uvx astro-airflow-mcp --transport stdio

Desktop Apps

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["astro-airflow-mcp", "--transport", "stdio"]
    }
  }
}

Other MCP Clients

Add to your MCP configuration file:

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["astro-airflow-mcp", "--transport", "stdio"]
    }
  }
}

Or connect to a running HTTP server: "url": "http://localhost:8000/mcp"

Note: No installation required - uvx runs directly from PyPI. The --transport stdio flag is required because the server defaults to HTTP mode.

Configuration

By default, the server connects to http://localhost:8080 (Astro CLI default). Set environment variables for custom Airflow instances:

Example with auth (Claude Code):

claude mcp add airflow -e AIRFLOW_API_URL=https://your-airflow.example.com -e AIRFLOW_USERNAME=admin -e AIRFLOW_PASSWORD=admin -- uvx astro-airflow-mcp --transport stdio

Features

• Airflow 2.x and 3.x Support: Automatic version detection with adapter pattern

• MCP Tools for accessing Airflow data:

  • DAG management (list, get details, get source code, stats, warnings, import errors, trigger, pause/unpause)

  • Task management (list, get details, get task instances, get logs)

  • Pool management (list, get details)

  • Variable management (list, get specific variables)

  • Connection management (list connections with credentials excluded)

  • Asset/Dataset management (unified naming across versions, data lineage)

  • Plugin and provider information

  • Configuration and version details

• Consolidated Tools for agent workflows:

  • explore_dag: Get comprehensive DAG information in one call

  • diagnose_dag_run: Debug failed DAG runs with task instance details

  • get_system_health: System overview with health, errors, and warnings

• MCP Resources: Static Airflow info exposed as resources (version, providers, plugins, config)

• MCP Prompts: Guided workflows for common tasks (troubleshooting, health checks, onboarding)

• Dual deployment modes:

  • Standalone server: Run as an independent MCP server

  • Airflow plugin: Integrate directly into Airflow 3.x webserver

• Flexible Authentication:

  • Bearer token (Airflow 2.x and 3.x)

  • Username/password with automatic OAuth2 token exchange (Airflow 3.x)

  • Basic auth (Airflow 2.x)

Available Tools

Consolidated Tools (Agent-Optimized)

Core Tools

MCP Resources

MCP Prompts

Advanced Usage

Running as Standalone Server

For HTTP-based integrations or connecting multiple clients to one server:

# Run server (HTTP mode is default)
uvx astro-airflow-mcp --airflow-url https://my-airflow.example.com --username admin --password admin

Connect MCP clients to: http://localhost:8000/mcp

Airflow Plugin Mode

Install into your Airflow 3.x environment to expose MCP at http://your-airflow:8080/mcp/v1:

# Add to your Astro project
echo astro-airflow-mcp >> requirements.txt

CLI Options

Architecture

The server is built using FastMCP with an adapter pattern for Airflow version compatibility:

Core Components

• Adapters (adapters/): Version-specific API implementations

  • AirflowAdapter (base): Abstract interface for all Airflow API operations

  • AirflowV2Adapter: Airflow 2.x API (/api/v1) with basic auth

  • AirflowV3Adapter: Airflow 3.x API (/api/v2) with OAuth2 token exchange

• Version Detection: Automatic detection at startup by probing API endpoints

• Models (models.py): Pydantic models for type-safe API responses

Version Handling Strategy

1. Major versions (2.x vs 3.x): Adapter pattern with runtime version detection

2. Minor versions (3.1 vs 3.2): Runtime feature detection with graceful fallbacks

3. New API parameters: Pass-through **kwargs for forward compatibility

Deployment Modes

• Standalone: Independent ASGI application with HTTP/SSE transport

• Plugin: Mounted into Airflow 3.x FastAPI webserver

Development

# Setup development environment
make install-dev

# Run tests
make test

# Run all checks
make check

# Local testing with Astro CLI
astro dev start  # Start Airflow
make run         # Run MCP server (connects to localhost:8080)

Contributing

Contributions welcome! Please ensure:

• All tests pass (make test)

• Code passes linting (make check)

• prek hooks pass (make prek)