mcp-airflow-simple

servidor mcp simples para Airflow 3 (versão 2 da API)

Documentação

Airflow MCP Server

Um servidor Model Context Protocol (MCP) para Apache Airflow 3 que fornece ferramentas essenciais para gerenciamento de DAGs, monitoramento, depuração e teste de conexões por meio da API REST v2 do Airflow.

Início Rápido

1. Crie o arquivo '.env'

cp .env.example .env

2. Instale as dependências

pip install -r requirements.txt

ele retornará um token, copie o token e cole-o no arquivo .env

3. Obtenha o token do Airflow

certifique-se de que seu Airflow esteja em execução e acessível na URL configurada

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

Exemplo:

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

4. Configure o servidor MCP

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

Recursos

🚀 Gerenciamento de DAGs

Listar todos os DAGs com opções de filtro
Obter tarefas dentro de um DAG específico
Disparar execuções de DAG com configuração opcional
Limpar/repetir execuções de DAG com falha

🔍 Monitoramento e Status

Verificar histórico e status das execuções de DAG
Visualizar instâncias de tarefas para execuções específicas
Obter estatísticas agregadas de DAGs

🐛 Depuração e Logs

Recuperar logs de execução de tarefas
Verificar erros de importação/parse de DAGs

🔌 Gerenciamento de Conexões

Listar todas as conexões do Airflow
Obter detalhes da conexão
Testar acessibilidade da conexão

🏥 Verificações de Saúde

Monitorar o status do Scheduler, Metadatabase, Triggerer e DagProcessor do Airflow

Instalação

Clone ou navegue até o diretório do projeto:
```
cd c:\{your_path_to}\mcp-airflow
```
Instale as dependências:
```
pip install -r requirements.txt
```

Configure as variáveis de ambiente: Edite o arquivo .env com os detalhes da sua instância do 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

Configuração

O servidor suporta dois métodos de autenticação:

Token JWT (Preferido): Defina airflow_jwt_token em .env
Autenticação Básica (Fallback): Usa airflow_username e airflow_password

O servidor usará automaticamente JWT se disponível, caso contrário, recorrerá à autenticação básica.

Ferramentas MCP Disponíveis

Gerenciamento de DAGs

`get_dags`

Liste todos os DAGs no Airflow.

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

`get_dag_tasks`

Obtenha todas as tarefas em um DAG específico.

{
  "dag_id": "example_dag"
}

`trigger_dag_run`

Dispare uma nova execução de DAG.

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

`clear_dag_run`

Limpe/reexecute uma execução de DAG (redefine tarefas com falha).

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

`set_dag_state`

Pause ou retome um DAG.

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

Monitoramento e Status

`get_dag_runs`

Obtenha o histórico de execuções de DAG com filtro opcional de estado.

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

`get_task_instances`

Obtenha instâncias de tarefas para uma execução de DAG específica.

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

`get_dag_stats`

Obtenha estatísticas agregadas para todos os DAGs.

{}

Depuração e Logs

`get_task_logs`

Obtenha logs de execução para uma instância de tarefa 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`

Obtenha erros de importação/parse de DAGs.

{}

Gerenciamento de Conexões

`get_connections`

Liste todas as conexões do Airflow.

{
  "limit": 100
}

`get_connection`

Obtenha detalhes de uma conexão específica.

{
  "connection_id": "postgres_default"
}

`test_connection`

Teste a acessibilidade da conexão.

{
  "connection_id": "postgres_default"
}

Verificação de Saúde

`check_health`

Verifique a saúde do sistema Airflow (inclui Metadatabase, Scheduler, Triggerer e DagProcessor).

{}

Executando o Servidor

Como um Servidor MCP (Stdio)

O servidor é executado como um servidor MCP baseado em stdio:

python server.py

Integração com Clientes MCP

Para usar este servidor com clientes MCP como o Claude Desktop, adicione à sua configuração 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"]
    }
  }
}

Solução de Problemas

Problemas de Conexão

Verifique se o Airflow está em execução e acessível na URL configurada
Verifique as credenciais de autenticação (token JWT ou nome de usuário/senha)
Certifique-se de que a API REST do Airflow esteja habilitada

Erros de Autenticação

Confirme se o token JWT é válido e não expirou
Verifique se o nome de usuário e a senha estão corretos
Verifique se o usuário tem as permissões necessárias no Airflow

Erros de Ferramentas

Certifique-se de que os IDs de DAG e IDs de execução estejam corretos
Verifique se os recursos solicitados existem no Airflow
Revise os logs do Airflow para obter contexto adicional

Referência da API

Este servidor MCP usa a API REST v2 do Airflow. Para documentação detalhada da API, consulte:

Documentação da API REST do Airflow
Especificação OpenAPI local: openapi.json

Requisitos

Python 3.8+
Apache Airflow 3.x com API REST habilitada
Acesso de rede à instância do Airflow

Licença

Licença MIT - sinta-se à vontade para usar e modificar conforme necessário.