Airflow MCP Server

A Model Context Protocol (MCP) server for Apache Airflow 3 that provides essential tools for DAG management, monitoring, debugging, and connection testing through the Airflow REST API v2.

Features

🚀 DAG Management

• List all DAGs with filtering options
• Get tasks within a specific DAG
• Trigger DAG runs with optional configuration
• Clear/retry failed DAG runs

🔍 Monitoring & Status

• Check DAG run history and status
• View task instances for specific runs
• Get aggregate DAG statistics

🐛 Debugging & Logs

• Retrieve task execution logs
• Check DAG import/parsing errors

🔌 Connection Management

• List all Airflow connections
• Get connection details
• Test connection accessibility

🏥 Health Checks

• Monitor Airflow Scheduler, Metadatabase, Triggerer, and DagProcessor status

Available MCP Tools

DAG Management

get_dags

List all DAGs in Airflow.

{
  "only_active": false,
  "limit": 100
}

get_dag_tasks

Get all tasks in a specific DAG.

{
  "dag_id": "example_dag"
}

trigger_dag_run

Trigger a new DAG run.

{
  "dag_id": "example_dag",
  "conf": {"key": "value"},
  "logical_date": "2026-01-05T00:00:00Z"
}

clear_dag_run

Clear/retry a DAG run (resets failed tasks).

{
  "dag_id": "example_dag",
  "dag_run_id": "manual__2026-01-05T00:00:00+00:00",
  "dry_run": false
}

set_dag_state

Pause or unpause a DAG.

{
  "dag_id": "example_dag",
  "is_paused": true
}

Monitoring & Status

get_dag_runs

Get DAG run history with optional state filtering.

{
  "dag_id": "example_dag",
  "state": "failed",
  "limit": 25
}

get_task_instances

Get task instances for a specific DAG run.

{
  "dag_id": "example_dag",
  "dag_run_id": "manual__2026-01-05T00:00:00+00:00"
}

get_dag_stats

Get aggregate statistics for all DAGs.

{}

Debugging & Logs

get_task_logs

Get execution logs for a specific task instance.

{
  "dag_id": "example_dag",
  "dag_run_id": "manual__2026-01-05T00:00:00+00:00",
  "task_id": "example_task",
  "try_number": 1
}

get_import_errors

Get DAG import/parsing errors.

{}

Connection Management

get_connections

List all Airflow connections.

{
  "limit": 100
}

get_connection

Get details of a specific connection.

{
  "connection_id": "postgres_default"
}

test_connection

Test connection accessibility.

{
  "connection_id": "postgres_default"
}

Health Check

check_health

Check Airflow system health (includes Metadatabase, Scheduler, Triggerer, and DagProcessor).

{}

API Reference

This MCP server uses the Airflow REST API v2. For detailed API documentation, see:

• Airflow REST API Documentation
• Local OpenAPI spec: openapi.json

Quick Start

1. Create '.env' file

cp .env.example .env

2. Install dependencies

pip install -r requirements.txt

it will return a token, copy the token and paste it to the .env file

3. Get the airflow token

make sure your airflow is running and accessible at the configured URL

curl -X POST "{your_ariflow_url}/auth/token" -H "Content-Type: application/json" -d '{"username":"{your_airflow_username}","password":"{your_airflow_password}"}'

Example:

curl -X POST "http://localhost:8080/auth/token" -H "Content-Type: application/json" -d '{"username":"airflow","password":"airflow"}'

4. config the MCP server

{
  "mcpServers": {
    "airflow": {
      "command": "python",
      "args": ["c:\\{path_to_your_folder}\\mcp-airflow-simple\\server.py"],
      "env": {
        "GIT_AUTO_UPDATE": "true"
      }
    }
  }
}

Installation

1. Clone or navigate to the project directory:

   Copy

   cd c:\{your_path_to}\mcp-airflow

2. Install dependencies:

   Copy

   pip install -r requirements.txt

3. Configure environment variables: Edit the .env file with your Airflow instance details:

   Copy

   airflow_baseurl=http://localhost:8080
   airflow_api_url=http://localhost:8080/api/v2
   airflow_username=airflow
   airflow_password=airflow
   airflow_jwt_token=your_jwt_token_here

Configuration

The server supports two authentication methods:

1. JWT Token (Preferred): Set airflow_jwt_token in .env
2. Basic Auth (Fallback): Uses airflow_username and airflow_password

The server will automatically use JWT if available, otherwise fall back to basic authentication.

Running the Server

As an MCP Server (Stdio)

The server runs as a stdio-based MCP server:

python server.py

Integration with MCP Clients

To use this server with MCP clients like Claude Desktop, add to your MCP configuration:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "airflow": {
      "command": "python",
      "args": ["c:\\{path_to_your_folder}\\mcp-airflow\\server.py"],
      "env": {
        "airflow_api_url": "http://localhost:8080/api/v2",
        "airflow_jwt_token": "your_token_here"
      }
    }
  }
}

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "airflow": {
      "command": "python3",
      "args": ["{path_to_your_folder}/mcp-airflow/server.py"]
    }
  }
}

Requirements

• Python 3.8+
• Apache Airflow 3.x with REST API enabled
• Network access to Airflow instance

Troubleshooting

Connection Issues

• Verify Airflow is running and accessible at the configured URL
• Check authentication credentials (JWT token or username/password)
• Ensure the Airflow REST API is enabled

Authentication Errors

• Confirm JWT token is valid and not expired
• Verify username and password are correct
• Check that the user has necessary permissions in Airflow

Tool Errors

• Ensure DAG IDs and run IDs are correct
• Check that the requested resources exist in Airflow
• Review Airflow logs for additional context

License

MIT License - feel free to use and modify as needed.