# MCP Airflow API

> ⚡ Control Apache Airflow with natural language via MCP. Chat with your workflows using Claude, GPT, or any LLM — no REST API calls needed. Supports Airflow 2.x (43 tools) & 3.0+ (45+ tools).

- **Type:** MCP server
- **Install:** `agentstack add mcp-call518-mcp-airflow-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [call518](https://agentstack.voostack.com/s/call518)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [call518](https://github.com/call518)
- **Source:** https://github.com/call518/MCP-Airflow-API
- **Website:** https://deepwiki.com/call518/MCP-Airflow-API

## Install

```sh
agentstack add mcp-call518-mcp-airflow-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🚀 MCP-Airflow-API

> Revolutionary Open Source Tool for Managing Apache Airflow with Natural Language

[](https://opensource.org/licenses/MIT)

[](https://www.buymeacoffee.com/call518)

[](https://github.com/call518/MCP-Airflow-API/actions/workflows/pypi-publish.yml)

---

## Architecture & Internal (DeepWiki)

[](https://deepwiki.com/call518/MCP-Airflow-API)

---

## 📋 Overview

Have you ever wondered how amazing it would be if you could manage your Apache Airflow workflows using natural language instead of complex REST API calls or web interface manipulations? **MCP-Airflow-API** is the revolutionary open-source project that makes this goal a reality.

---

## 🎯 What is MCP-Airflow-API?

MCP-Airflow-API is an MCP server that leverages the **Model Context Protocol (MCP)** to transform Apache Airflow REST API operations into natural language tools. This project hides the complexity of API structures and enables intuitive management of Airflow clusters through natural language commands.

### 🆕 Multi-Version API Support (NEW!)

**Now supports both Airflow API v1 (2.x) and v2 (3.0+)** with dynamic version selection via environment variable:

- **API v1**: Full compatibility with Airflow 2.x clusters (43 tools) - [Documentation](https://airflow.apache.org/docs/apache-airflow/2.11.0/stable-rest-api-ref.html)
- **API v2**: Enhanced features for Airflow 3.0+ including asset management for data-aware scheduling (45 tools) - [Documentation](https://airflow.apache.org/docs/apache-airflow/3.1.0/stable-rest-api-ref.html)

**Key Architecture**: Single MCP server with shared common tools (43) plus v2-exclusive asset tools (2) - dynamically loads appropriate toolset based on `AIRFLOW_API_VERSION` environment variable!

**Traditional approach (example):**
```bash
curl -X GET "http://localhost:8080/api/v1/dags?limit=100&offset=0" \
  -H "Authorization: Basic YWlyZmxvdzphaXJmbG93"
```

**MCP-Airflow-API approach (natural language):**
> "Show me the currently running DAGs"

---

## 🚀 Quickstart

> **📝 Need a test Airflow cluster?** Use our companion project [**Airflow-Docker-Compose**](https://github.com/call518/Airflow-Docker-Compose) with support for both **Airflow 2.x** and **Airflow 3.x** environments!

### Flow Diagram of Quickstart/Tutorial

### 🎯 Recommended: Docker Compose (Complete Demo Environment)

**For quick evaluation and testing:**

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

# Configure your Airflow credentials
cp .env.example .env
# Edit .env with your Airflow API settings

# Start all services
docker-compose up -d

# Access OpenWebUI at http://localhost:3002/
# API documentation at http://localhost:8002/docs
```

### Getting Started with OpenWebUI (Docker Option)

> 📌 **Note**: Web-UI configuration instructions are based on OpenWebUI **v0.6.22**. Menu locations and settings may differ in newer versions.

1. Access http://localhost:3002/
2. Log in with admin account
3. Go to "Settings" → "Tools" from the top menu
4. Add Tool URL: `http://localhost:8002/airflow-api`
5. Configure your LLM provider (Ollama, OpenAI, etc.)

---

## 📦 MCP Server Installation Methods

### Method 1: Direct Installation from PyPI
```bash
uvx --python 3.12 mcp-airflow-api
```

### Method 2: Claude-Desktop MCP Client Integration

**Local Access (stdio mode)**

```json
{
  "mcpServers": {
    "mcp-airflow-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v2",
        "AIRFLOW_API_BASE_URL": "http://localhost:8080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    }
  }
}git
```

**Remote Access (streamable-http mode without authentication)**

```json
{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Remote Access (streamable-http mode with Bearer token authentication - Recommended)**

```json
{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}
```

**Multiple Airflow Clusters with Different Versions**

```json
{
  "mcpServers": {
    "airflow-2x-cluster": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v1",
        "AIRFLOW_API_BASE_URL": "http://localhost:38080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    },
    "airflow-3x-cluster": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v2",
        "AIRFLOW_API_BASE_URL": "http://localhost:48080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    }
  }
}
```

> **💡 Pro Tip**: Use the test clusters from [Airflow-Docker-Compose](https://github.com/call518/Airflow-Docker-Compose) for the above configuration - they run on ports 38080 (2.x) and 48080 (3.x) respectively!

### Method 3: Development Installation
```bash
git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API
pip install -e .

# Run in stdio mode
python -m mcp_airflow_api
```

---

## 🌟 Key Features

1. **Natural Language Queries**  
   No need to learn complex API syntax. Just ask as you would naturally speak:
   - "What DAGs are currently running?"
   - "Show me the failed tasks"
   - "Find DAGs containing ETL"

2. **Comprehensive Monitoring Capabilities**  
   Real-time cluster status monitoring:
   - Cluster health monitoring
   - DAG status and performance analysis
   - Task execution log tracking
   - XCom data management

3. **Dynamic API Version Support**  
   Single MCP server adapts to your Airflow version:
   - **API v1**: 43 shared tools for Airflow 2.x compatibility
   - **API v2**: 43 shared tools + 2 asset management tools for Airflow 3.0+
   - **Environment Variable Control**: Switch versions instantly with `AIRFLOW_API_VERSION`
   - **Zero Configuration Changes**: Same tool names, enhanced capabilities
   - **Efficient Architecture**: Shared common codebase eliminates duplication

4. **Comprehensive Tool Coverage**  
   Covers almost all Airflow API functionality:
   - DAG management (trigger, pause, resume)
   - Task instance monitoring
   - Pool and variable management
   - Connection configuration
   - Configuration queries
   - Event log analysis

4. **Large Environment Optimization**  
   Efficiently handles large environments with 1000+ DAGs:
   - Smart pagination support
   - Advanced filtering options
   - Batch processing capabilities

---

## 🛠️ Technical Advantages

- **Leveraging Model Context Protocol (MCP)**  
  MCP is an open standard for secure connections between AI applications and data sources, providing:
  - Standardized interface
  - Secure data access
  - Scalable architecture

- **Support for Two Transport Modes**
  - `stdio` mode: Direct MCP client integration for local environments
  - `streamable-http` mode: HTTP-based deployment for Docker and remote access
  
  **Environment Variable Control:**
  ```bash
  FASTMCP_TYPE=stdio          # Default: Direct MCP client mode
  FASTMCP_TYPE=streamable-http # Docker/HTTP mode
  FASTMCP_PORT=8000           # HTTP server port (Docker internal)
  ```

- **Comprehensive Airflow API Coverage**  
  Full implementation of official Airflow REST APIs:
  - **API v1 Support**: Based on [Airflow 2.x REST API](https://airflow.apache.org/docs/apache-airflow/2.0.0/stable-rest-api-ref.html)
  - **API v2 Support**: Based on [Airflow 3.0+ REST API](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html)
  - **Dynamic Version Selection**: Runtime switching between API versions
  - **Feature Parity**: Complete endpoint coverage for both versions

- **Complete Docker Support**  
  Full Docker Compose setup with 3 separate services:
  - **Open WebUI**: Web interface (port `3002`)
  - **MCP Server**: Airflow API tools (internal port `8000`, exposed via `18002`)
  - **MCPO Proxy**: REST API endpoint provider (port `8002`)

---

## Use Cases in Action

---

---

---

---

---

---

---

---

---

---

---

## ⚙️ Advanced Configuration

### Environment Variables
```bash
# Required - Dynamic API Version Selection (NEW!)
# Single server supports both v1 and v2 - just change this variable!
AIRFLOW_API_VERSION=v1           # v1 for Airflow 2.x, v2 for Airflow 3.0+
AIRFLOW_API_BASE_URL=http://localhost:8080/api

# Test Cluster Connection Examples:
# For Airflow 2.x test cluster (from Airflow-Docker-Compose)
AIRFLOW_API_VERSION=v1
AIRFLOW_API_BASE_URL=http://localhost:38080/api

# For Airflow 3.x test cluster (from Airflow-Docker-Compose)  
AIRFLOW_API_VERSION=v2
AIRFLOW_API_BASE_URL=http://localhost:48080/api

# Authentication
AIRFLOW_API_USERNAME=airflow
AIRFLOW_API_PASSWORD=airflow

# Optional - MCP Server Configuration
MCP_LOG_LEVEL=INFO                   # DEBUG/INFO/WARNING/ERROR/CRITICAL
FASTMCP_TYPE=stdio                   # stdio/streamable-http
FASTMCP_PORT=8000                    # HTTP server port (Docker mode)

# Bearer Token Authentication for streamable-http mode
# Enable authentication (recommended for production)
# Default: false (when undefined, empty, or null)
# Values: true/false, 1/0, yes/no, on/off (case insensitive)
REMOTE_AUTH_ENABLE=false             # true/false
REMOTE_SECRET_KEY=your-secure-secret-key-here
```

### API Version Comparison

**Official Documentation:**
- **API v1**: [Airflow 2.x REST API Reference](https://airflow.apache.org/docs/apache-airflow/2.0.0/stable-rest-api-ref.html)
- **API v2**: [Airflow 3.0+ REST API Reference](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html)

| Feature | API v1 (Airflow 2.x) | API v2 (Airflow 3.0+) |
|---------|----------------------|----------------------|
| **Total Tools** | **43 tools** | **45 tools** |
| **Shared Tools** | 43 (100%) | 43 (96%) |
| **Exclusive Tools** | 0 | 2 (Asset Management) |
| Basic DAG Operations | ✅ | ✅ Enhanced |
| Task Management | ✅ | ✅ Enhanced |
| Connection Management | ✅ | ✅ Enhanced |
| Pool Management | ✅ | ✅ Enhanced |
| **Asset Management** | ❌ | ✅ **New** |
| **Asset Events** | ❌ | ✅ **New** |
| **Data-Aware Scheduling** | ❌ | ✅ **New** |
| **Enhanced DAG Warnings** | ❌ | ✅ **New** |
| **Advanced Filtering** | Basic | ✅ **Enhanced** |

---

## 🔐 Security & Authentication

### Bearer Token Authentication

For `streamable-http` mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

#### Configuration

**Enable Authentication:**

```bash
# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here
```

**Or via CLI:**

```bash
python -m mcp_airflow_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here
```

#### Security Levels

1. **stdio mode** (Default): Local-only access, no authentication needed
2. **streamable-http + REMOTE_AUTH_ENABLE=false**: Remote access without authentication ⚠️ **NOT RECOMMENDED for production**
3. **streamable-http + REMOTE_AUTH_ENABLE=true**: Remote access with Bearer token authentication ✅ **RECOMMENDED for production**

> **Note**: `REMOTE_AUTH_ENABLE` defaults to `false` when undefined, empty, or null. Supported values are `true/false`, `1/0`, `yes/no`, `on/off` (case insensitive).

#### Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

```json
{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}
```

#### Security Best Practices

- **Always enable authentication** when using streamable-http mode in production
- **Use strong, randomly generated secret keys** (32+ characters recommended)
- **Use HTTPS** when possible (configure reverse proxy with SSL/TLS)
- **Restrict network access** using firewalls or network policies
- **Rotate secret keys regularly** for enhanced security
- **Monitor access logs** for unauthorized access attempts

#### Error Handling

When authentication fails, the server returns:
- **401 Unauthorized** for missing or invalid tokens
- **Detailed error messages** in JSON format for debugging

---

### Custom Docker Compose Setup
```yaml
version: '3.8'
services:
  mcp-server:
    build: 
      context: .
      dockerfile: Dockerfile.MCP-Server
    environment:
      - FASTMCP_PORT=8000
      - AIRFLOW_API_VERSION=v1
      - AIRFLOW_API_BASE_URL=http://your-airflow:8080/api
      - AIRFLOW_API_USERNAME=airflow
      - AIRFLOW_API_PASSWORD=airflow
```

### Development Installation
```bash
git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API
pip install -e .

# Run in stdio mode
python -m mcp_airflow_api
```

---

## 🧪 Test Airflow Cluster Deployment

For testing and development, use our companion project [**Airflow-Docker-Compose**](https://github.com/call518/Airflow-Docker-Compose) which supports both Airflow 2.x and 3.x environments.

### Quick Setup

1. **Clone the test environment repository:**
   ```bash
   git clone https://github.com/call518/Airflow-Docker-Compose.git
   cd Airflow-Docker-Compose
   ```

### Option 1: Deploy Airflow 2.x (LTS)

For testing **API v1** compatibility with stable production features:

```bash
# Navigate to Airflow 2.x environment
cd airflow-2.x

# (Optional) Customize environment variables
cp .env.template .env
# Edit .env file as needed

# Deploy Airflow 2.x cluster
./run-airflow-cluster.sh

# Access Web UI
# URL: http://localhost:38080
# Username: airflow / Password: airflow
```

**Environment details:**
- **Image**: `apache/airflow:2.10.2`
- **Port**: `38080` (configurable via `AIRFLOW_WEBSERVER_PORT`)
- **API**: `/api/v1/*` endpoints
- **Authentication**: Basic Auth
- **Use case**: Production-ready, stable features

### Option 2: Deploy Airflow 3.x (Latest)

For testing **API v2** with latest features including Assets management:

```bash
# Navigate to Airflow 3.x environment  
cd airflow-3.x

# (Optional) Customize environment variables
cp .env.template .env
# Edit .env file as needed

# Deploy Airflow 3.x cluster
./run-airflow-cluster.sh

# Access API Server
# URL: http://localhost:48080
# Username: airflow / Password: airflow
```

**Environment details:**
- **Image**: `apache/airflow:3.0.6`
- **Port**: `48080` (configurable via `AIRFLOW_APISERVER_PORT`)
- **API**: `/api/v2/*` endpoints + Assets management
- **Authentication**: JWT Token (FabAuthManager)
- **Use case**: Development, testing new features

### Option 3: Deploy Both Versions Simultaneously

For comprehensive testing across different Airflow versions:

```bash
# Start Airflow 2.x (port 38080)
cd airflow-2.x && ./run-airflow-cluster.sh

# Start Airflow 3.x (port 48080) 
cd ../airflow-3.x && ./run-airflow-cluster.sh
```

### Key Differences

| Feature | Airflow 2.x | Airflow 3.x |
|---------|-------------|-------------|
| **Authentication** | Basic Auth | JWT Tokens (FabAuthManager) |
| **Default Port** | 38080 | 48080 |
| **API Endpoints** | `/api/v1/*` | `/api/v2/*` |
| **Assets Support** | ❌ Limited/Experimental | ✅ Full Support |
| **Provider Packages** | providers | distributions |
| **Stability** | ✅ Production Ready | 🧪 Beta/Development |

### Cleanup

To stop and clean up the test environments:

```bash
# For Airflow 2.x
cd airflow-2.x && ./cleanup-airflow-cluster.sh

# For Airflow 3.x
cd airflow-3.x && ./cleanup-airflow-cluster.sh
```

---

## 🌈 Future-Ready Architecture

- Scalable design and modular structure for easy addition of new features  
- Standards-compliant protocol for integration with

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [call518](https://github.com/call518)
- **Source:** [call518/MCP-Airflow-API](https://github.com/call518/MCP-Airflow-API)
- **License:** MIT
- **Homepage:** https://deepwiki.com/call518/MCP-Airflow-API

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-call518-mcp-airflow-api
- Seller: https://agentstack.voostack.com/s/call518
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.