Airflow Monitor

A FastMCP-based Model Context Protocol server for monitoring Apache Airflow DAGs. Provides read-only real-time access to DAG status, execution history, and performance metrics. Agents using this server cannot modify, trigger, or pause any DAGs.

Security Note: This server is intentionally read-only for safe integration with untrusted clients and AI agents.

Features

• List Active DAGs: Query all active DAGs with metadata (description, owner, schedule)
• Recent Runs: Fetch recent execution runs for specific DAGs with timing and status
• Execution History: Analyze DAG performance over configurable time periods with success rates and average durations
• Stdio Transport: Lightweight stdio-based MCP interface for seamless integration with Claude and other MCP clients
• READ-ONLY Access: Safe monitoring interface with no write operations—agents can only read DAG status and metrics

⚠️ Read-Only Server

This is a READ-ONLY MCP server. Agents and clients using this server have no write access to Airflow. All tools provide monitoring and analysis capabilities only:

• ✓ Query DAG status and metadata
• ✓ View execution history and performance metrics
• ✓ Monitor recent runs and logs
• ✗ No ability to pause/resume DAGs
• ✗ No ability to trigger DAG runs
• ✗ No ability to modify DAG configurations
• ✗ No ability to clear task states

Safe for integration with untrusted agents and AI models without risk of accidental modifications.

Requirements

• Python 3.11+
• Apache Airflow instance with API access
• Docker & Docker Compose (for containerized deployment)

Installation

Local Setup

# Clone and navigate to project directory
cd "airflow-monitor-mcp"

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Environment Configuration

Create a .env file in the project root:

AIRFLOW_URL=
AIRFLOW_USERNAME=
AIRFLOW_PASSWORD=

Usage

Local Execution

python airflow_mcp.py

The MCP server will start and communicate via stdin/stdout using the Model Context Protocol.

Docker Deployment

docker-compose up -d

The containerized MCP server will initialize and be ready to accept stdio connections:

docker-compose logs -f

MCP Server Demo with Claude Desktop

https://github.com/user-attachments/assets/52e9249e-df37-4826-9d7e-3d226e9c471a

API Tools

All tools are READ-ONLY monitoring operations:

list_active_dags()

Returns all active DAGs with metadata.

Returns:

• dag_id: Unique DAG identifier
• description: DAG description
• owner: DAG owner
• schedule_interval: Schedule interval
• is_paused: Pause status
• next_dagrun: Next scheduled run time

get_recent_runs(dag_id, limit=10)

Fetch recent execution runs for a DAG.

Parameters:

• dag_id (str): Target DAG ID
• limit (int): Number of runs to fetch (default: 10)

Returns:

• execution_date: Run execution timestamp
• state: Run state (success/failed/running)
• start_date: Run start time
• end_date: Run end time
• duration: Total execution duration

get_execution_history(dag_id, days=7)

Get DAG performance metrics over a time period.

Parameters:

• dag_id (str): Target DAG ID
• days (int): Lookback period in days (default: 7)

Returns:

• success_count: Successful runs
• failed_count: Failed runs
• success_rate: Success percentage
• avg_duration_seconds: Average run duration

Configuration

Variable	Description	Example
AIRFLOW_URL	Airflow instance base URL	http://localhost:8080
AIRFLOW_USERNAME	API authentication username	admin
AIRFLOW_PASSWORD	API authentication password	secure_password

Project Structure

Python Scripts/
├── airflow_mcp.py          # Main MCP server application
├── requirements.txt         # Python dependencies
├── .env.example            # Environment template
├── Dockerfile              # Container image definition
├── docker-compose.yml      # Multi-container orchestration
├── .dockerignore           # Docker build exclusions
└── README.md              # This file

Docker Deployment

The application includes Docker support with Python 3.11. See docker-compose.yml for configuration options.

Troubleshooting

Connection Error: Verify AIRFLOW_URL and credentials in .env
API 403 Errors: Ensure Airflow user has API permissions
Timeout Issues: Increase timeout in get_client() or check network connectivity

License

MIT