mcp-airflow-simple

Servidor MCP simple para Airflow 3 (versión 2 de la API)

Documentación

Servidor MCP de Airflow

Un servidor de Model Context Protocol (MCP) para Apache Airflow 3 que proporciona herramientas esenciales para la gestión de DAGs, monitoreo, depuración y pruebas de conexión a través de la API REST de Airflow v2.

Inicio Rápido

1. Crear el archivo '.env'

cp .env.example .env

2. Instalar dependencias

pip install -r requirements.txt

devolverá un token, copia el token y pégalo en el archivo .env

3. Obtener el token de Airflow

asegúrate de que tu Airflow esté en ejecución y sea accesible en la URL configurada

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

Ejemplo:

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

4. Configurar el servidor MCP

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

Características

🚀 Gestión de DAGs

Listar todos los DAGs con opciones de filtrado
Obtener tareas dentro de un DAG específico
Ejecutar DAGs con configuración opcional
Limpiar/reintentar ejecuciones de DAG fallidas

🔍 Monitoreo y Estado

Consultar el historial y estado de ejecuciones de DAGs
Ver instancias de tareas para ejecuciones específicas
Obtener estadísticas agregadas de DAGs

🐛 Depuración y Registros

Recuperar registros de ejecución de tareas
Verificar errores de importación/análisis de DAGs

🔌 Gestión de Conexiones

Listar todas las conexiones de Airflow
Obtener detalles de una conexión específica
Probar la accesibilidad de las conexiones

🏥 Verificaciones de Salud

Monitorear el estado del Scheduler, Metadatabase, Triggerer y DagProcessor de Airflow

Instalación

Clona o navega al directorio del proyecto:
```
cd c:\{your_path_to}\mcp-airflow
```
Instala las dependencias:
```
pip install -r requirements.txt
```

Configura las variables de entorno: Edita el archivo .env con los detalles de tu instancia de Airflow:

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

Configuración

El servidor admite dos métodos de autenticación:

Token JWT (Preferido): Establece airflow_jwt_token en .env
Autenticación Básica (Respaldo): Usa airflow_username y airflow_password

El servidor usará automáticamente JWT si está disponible; de lo contrario, recurrirá a la autenticación básica.

Herramientas MCP Disponibles

Gestión de DAGs

`get_dags`

Lista todos los DAGs en Airflow.

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

`get_dag_tasks`

Obtiene todas las tareas en un DAG específico.

{
  "dag_id": "example_dag"
}

`trigger_dag_run`

Ejecuta una nueva ejecución de DAG.

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

`clear_dag_run`

Limpia/reintenta una ejecución de DAG (restablece tareas fallidas).

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

`set_dag_state`

Pausa o reanuda un DAG.

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

Monitoreo y Estado

`get_dag_runs`

Obtiene el historial de ejecuciones de DAG con filtrado opcional por estado.

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

`get_task_instances`

Obtiene instancias de tareas para una ejecución de DAG específica.

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

`get_dag_stats`

Obtiene estadísticas agregadas para todos los DAGs.

{}

Depuración y Registros

`get_task_logs`

Obtiene registros de ejecución para una instancia de tarea específica.

{
  "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`

Obtiene errores de importación/análisis de DAGs.

{}

Gestión de Conexiones

`get_connections`

Lista todas las conexiones de Airflow.

{
  "limit": 100
}

`get_connection`

Obtiene detalles de una conexión específica.

{
  "connection_id": "postgres_default"
}

`test_connection`

Prueba la accesibilidad de una conexión.

{
  "connection_id": "postgres_default"
}

Verificación de Salud

`check_health`

Verifica la salud del sistema de Airflow (incluye Metadatabase, Scheduler, Triggerer y DagProcessor).

{}

Ejecutar el Servidor

Como Servidor MCP (Stdio)

El servidor se ejecuta como un servidor MCP basado en stdio:

python server.py

Integración con Clientes MCP

Para usar este servidor con clientes MCP como Claude Desktop, agrégalo a tu configuración de MCP:

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"]
    }
  }
}

Solución de Problemas

Problemas de Conexión

Verifica que Airflow esté en ejecución y sea accesible en la URL configurada
Revisa las credenciales de autenticación (token JWT o nombre de usuario/contraseña)
Asegúrate de que la API REST de Airflow esté habilitada

Errores de Autenticación

Confirma que el token JWT sea válido y no haya expirado
Verifica que el nombre de usuario y la contraseña sean correctos
Revisa que el usuario tenga los permisos necesarios en Airflow

Errores de Herramientas

Asegúrate de que los IDs de DAG y los IDs de ejecución sean correctos
Verifica que los recursos solicitados existan en Airflow
Revisa los registros de Airflow para obtener contexto adicional

Referencia de la API

Este servidor MCP utiliza la API REST de Airflow v2. Para documentación detallada de la API, consulta:

Documentación de la API REST de Airflow
Especificación OpenAPI local: openapi.json

Requisitos

Python 3.8+
Apache Airflow 3.x con API REST habilitada
Acceso de red a la instancia de Airflow

Licencia

Licencia MIT: siéntete libre de usar y modificar según sea necesario.