Airflow MCP Server

mcp-server-apache-airflow

Una implementación de servidor de Model Context Protocol (MCP) para Apache Airflow, que permite una integración perfecta con clientes MCP. Este proyecto proporciona una forma estandarizada de interactuar con Apache Airflow a través del Model Context Protocol.

Acerca de

Este proyecto implementa un servidor Model Context Protocol que envuelve la API REST de Apache Airflow, permitiendo que los clientes MCP interactúen con Airflow de forma estandarizada. Utiliza la biblioteca oficial del cliente de Apache Airflow para garantizar compatibilidad y mantenibilidad.

Estado de Implementación de Funcionalidades

Funcionalidad	Ruta de API	Estado
Gestión de DAG
Listar DAGs	/api/v1/dags	✅
Obtener detalles del DAG	/api/v1/dags/{dag_id}	✅
Pausar DAG	/api/v1/dags/{dag_id}	✅
Reanudar DAG	/api/v1/dags/{dag_id}	✅
Actualizar DAG	/api/v1/dags/{dag_id}	✅
Eliminar DAG	/api/v1/dags/{dag_id}	✅
Obtener fuente del DAG	/api/v1/dagSources/{file_token}	✅
Parchear múltiples DAGs	/api/v1/dags	✅
Reanalizar archivo DAG	/api/v1/dagSources/{file_token}/reparse	✅
Ejecuciones de DAG
Listar ejecuciones de DAG	/api/v1/dags/{dag_id}/dagRuns	✅
Crear ejecución de DAG	/api/v1/dags/{dag_id}/dagRuns	✅
Obtener detalles de la ejecución del DAG	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
Actualizar ejecución de DAG	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
Eliminar ejecución de DAG	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
Obtener ejecuciones de DAG en lote	/api/v1/dags/~/dagRuns/list	✅
Limpiar ejecución de DAG	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/clear	✅
Establecer nota de la ejecución de DAG	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/setNote	✅
Obtener eventos de conjuntos de datos ascendentes	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamDatasetEvents	✅
Tareas
Listar tareas del DAG	/api/v1/dags/{dag_id}/tasks	✅
Obtener detalles de la tarea	/api/v1/dags/{dag_id}/tasks/{task_id}	✅
Obtener instancia de tarea	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
Listar instancias de tarea	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances	✅
Actualizar instancia de tarea	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
Obtener registro de instancia de tarea	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/logs/{task_try_number}	✅
Limpiar instancias de tarea	/api/v1/dags/{dag_id}/clearTaskInstances	✅
Establecer estado de las instancias de tarea	/api/v1/dags/{dag_id}/updateTaskInstancesState	✅
Listar intentos de instancia de tarea	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/tries	✅
Variables
Listar variables	/api/v1/variables	✅
Crear variable	/api/v1/variables	✅
Obtener variable	/api/v1/variables/{variable_key}	✅
Actualizar variable	/api/v1/variables/{variable_key}	✅
Eliminar variable	/api/v1/variables/{variable_key}	✅
Conexiones
Listar conexiones	/api/v1/connections	✅
Crear conexión	/api/v1/connections	✅
Obtener conexión	/api/v1/connections/{connection_id}	✅
Actualizar conexión	/api/v1/connections/{connection_id}	✅
Eliminar conexión	/api/v1/connections/{connection_id}	✅
Probar conexión	/api/v1/connections/test	✅
Pools
Listar pools	/api/v1/pools	✅
Crear pool	/api/v1/pools	✅
Obtener pool	/api/v1/pools/{pool_name}	✅
Actualizar pool	/api/v1/pools/{pool_name}	✅
Eliminar pool	/api/v1/pools/{pool_name}	✅
XComs
Listar XComs	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries	✅
Obtener entrada XCom	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries/{xcom_key}	✅
Conjuntos de datos
Listar conjuntos de datos	/api/v1/datasets	✅
Obtener conjunto de datos	/api/v1/datasets/{uri}	✅
Obtener eventos de conjuntos de datos	/api/v1/datasetEvents	✅
Crear evento de conjunto de datos	/api/v1/datasetEvents	✅
Obtener evento en cola de conjunto de datos del DAG	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
Obtener eventos en cola de conjuntos de datos del DAG	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
Eliminar evento en cola de conjunto de datos del DAG	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
Eliminar eventos en cola de conjuntos de datos del DAG	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
Obtener eventos en cola de conjuntos de datos	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
Eliminar eventos en cola de conjuntos de datos	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
Monitoreo
Obtener salud	/api/v1/health	✅
Estadísticas de DAG
Obtener estadísticas del DAG	/api/v1/dags/statistics	✅
Configuración
Obtener configuración	/api/v1/config	✅
Plugins
Obtener plugins	/api/v1/plugins	✅
Proveedores
Listar proveedores	/api/v1/providers	✅
Registros de eventos
Listar registros de eventos	/api/v1/eventLogs	✅
Obtener registro de eventos	/api/v1/eventLogs/{event_log_id}	✅
Sistema
Obtener errores de importación	/api/v1/importErrors	✅
Obtener detalles del error de importación	/api/v1/importErrors/{import_error_id}	✅
Obtener estado de salud	/api/v1/health	✅
Obtener versión	/api/v1/version	✅

Configuración

Dependencias

Este proyecto depende de la biblioteca oficial del cliente de Apache Airflow (apache-airflow-client). Se instalará automáticamente cuando instale este paquete.

Variables de entorno

Establezca las siguientes variables de entorno:

AIRFLOW_HOST=<your-airflow-host>        # Optional, defaults to http://localhost:8080
AIRFLOW_API_VERSION=v1                  # Optional, defaults to v1
READ_ONLY=true                          # Optional, enables read-only mode (true/false, defaults to false)

Autenticación

Elija uno de los siguientes métodos de autenticación:

Autenticación básica (predeterminada):

AIRFLOW_USERNAME=<your-airflow-username>
AIRFLOW_PASSWORD=<your-airflow-password>

Autenticación con token JWT:

AIRFLOW_JWT_TOKEN=<your-jwt-token>

Para obtener un token JWT, puede utilizar el endpoint de autenticación de Airflow:

ENDPOINT_URL="http://localhost:8080"  # Replace with your Airflow endpoint
curl -X 'POST' \
  "${ENDPOINT_URL}/auth/token" \
  -H 'Content-Type: application/json' \
  -d '{ "username": "<your-username>", "password": "<your-password>" }'

Nota: Si se proporcionan tanto el token JWT como las credenciales de autenticación básica, el token JWT tiene prioridad.

Uso con Claude Desktop

Agregue a su claude_desktop_config.json:

Autenticación básica:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password"
      }
    }
  }
}

Autenticación con token JWT:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

Para modo de solo lectura (recomendado por seguridad):

Autenticación básica:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password",
        "READ_ONLY": "true"
      }
    }
  }
}

Autenticación con token JWT:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uvx",
      "args": ["mcp-server-apache-airflow", "--read-only"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

Configuración alternativa usando uv:

Autenticación básica:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-apache-airflow",
        "run",
        "mcp-server-apache-airflow"
      ],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_USERNAME": "your-username",
        "AIRFLOW_PASSWORD": "your-password"
      }
    }
  }
}

Autenticación con token JWT:

{
  "mcpServers": {
    "mcp-server-apache-airflow": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-apache-airflow",
        "run",
        "mcp-server-apache-airflow"
      ],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

Reemplaza /path/to/mcp-server-apache-airflow con la ruta real donde has clonado el repositorio.

Selección de los grupos de API

Puedes seleccionar los grupos de API que deseas usar configurando la bandera --apis.

uv run mcp-server-apache-airflow --apis dag --apis dagrun

El valor predeterminado es usar todas las APIs.

Los valores permitidos son:

• config
• connections
• dag
• dagrun
• dagstats
• dataset
• eventlog
• importerror
• monitoring
• plugin
• pool
• provider
• taskinstance
• variable
• xcom

Modo de solo lectura

Puedes ejecutar el servidor en modo de solo lectura usando la bandera --read-only o configurando la variable de entorno READ_ONLY=true. Esto solo expondrá herramientas que realizan operaciones de lectura (solicitudes GET) y excluirá cualquier herramienta que cree, actualice o elimine recursos.

Usando la bandera de línea de comandos:

uv run mcp-server-apache-airflow --read-only

Usando la variable de entorno:

READ_ONLY=true uv run mcp-server-apache-airflow

En modo de solo lectura, el servidor solo expondrá herramientas como:

• Listar DAGs, ejecuciones de DAG, tareas, variables, conexiones, etc.
• Obtener detalles de recursos específicos
• Leer configuraciones e información de monitoreo
• Probar conexiones (no destructivo)

Las operaciones de escritura como crear, actualizar, eliminar DAGs, variables, conexiones, activar ejecuciones de DAG, etc. no estarán disponibles en modo de solo lectura.

Puedes combinar el modo de solo lectura con la selección de grupos de API:

uv run mcp-server-apache-airflow --read-only --apis dag --apis variable

Ejecución manual

También puedes ejecutar el servidor manualmente:

make run

make run acepta las siguientes opciones:

Opciones:

• --port: Puerto para escuchar en SSE (predeterminado: 8000)
• --transport: Tipo de transporte (stdio/sse/http, predeterminado: stdio)

O bien, puedes ejecutar el servidor sse directamente, que acepta los mismos parámetros:

make run-sse

También puedes iniciar el servicio directamente usando uv como en el siguiente comando:

uv run src --transport http --port 8080

Instalación mediante Smithery

Para instalar Apache Airflow MCP Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @yangkyeongmo/mcp-server-apache-airflow --client claude

Desarrollo

Configuración del entorno de desarrollo

1. Clona el repositorio:

git clone https://github.com/yangkyeongmo/mcp-server-apache-airflow.git
cd mcp-server-apache-airflow

2. Instala las dependencias de desarrollo:

uv sync --dev

3. Crea un archivo .env para las variables de entorno (opcional para desarrollo):

touch .env

Nota: No se requieren variables de entorno para ejecutar las pruebas. El AIRFLOW_HOST tiene como valor predeterminado http://localhost:8080 para fines de desarrollo y pruebas.

Ejecución de pruebas

El proyecto utiliza pytest para las pruebas con los siguientes comandos disponibles:

# Run all tests
make test

Calidad del código

# Run linting
make lint

# Run code formatting
make format

Integración continua

El proyecto incluye un flujo de trabajo de GitHub Actions (.github/workflows/test.yml) que automáticamente:

• Ejecuta pruebas en Python 3.10, 3.11 y 3.12
• Ejecuta comprobaciones de linting con ruff
• Se ejecuta en cada push y pull request a la rama main

El pipeline de CI garantiza la calidad del código y la compatibilidad en las versiones de Python compatibles antes de que se fusionen los cambios.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

El paquete se implementa automáticamente en PyPI cuando se actualiza project.version en pyproject.toml. Sigue semver para el versionado.

Incluye la actualización de versión en el PR para poder aplicar los cambios a la lógica principal.

Licencia

MIT License