MCP-气流-API

Name: MCP-气流-API
Author: call518

作者：call51842 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

🚀 MCP-Airflow-API

革命性的开源工具，使用自然语言管理Apache Airflow

Docker Pulls

PyPI PyPI - Downloads

架构与内部（DeepWiki）

📋 概述

您是否曾想过，如果能够使用自然语言而不是复杂的REST API调用或网页界面操作来管理您的Apache Airflow工作流，那该有多好？MCP-Airflow-API 是一个革命性的开源项目，使这一目标成为现实。

MCP-Airflow-API 截图

🎯 MCP-Airflow-API 是什么？

MCP-Airflow-API 是一个利用**模型上下文协议（MCP）**将Apache Airflow REST API操作转换为自然语言工具的MCP服务器。该项目隐藏了API结构的复杂性，并通过自然语言命令实现了对Airflow集群的直观管理。

🆕 多版本API支持（新功能！）

现在同时支持Airflow API v1（2.x）和v2（3.0+），并通过环境变量动态选择版本：

API v1：完全兼容Airflow 2.x集群（43个工具） - 文档
API v2：增强功能，适用于Airflow 3.0+，包括数据感知调度的资产管理（45个工具） - 文档

关键架构：单个MCP服务器共享通用工具（43个）加上v2独有资产工具（2个） - 根据AIRFLOW_API_VERSION环境变量动态加载合适的工具集！

传统方法（示例）：

curl -X GET "http://localhost:8080/api/v1/dags?limit=100&offset=0" \
  -H "Authorization: Basic YWlyZmxvdzphaXJmbG93"

MCP-Airflow-API 方法（自然语言）：

"显示当前正在运行的DAG"

🚀 快速入门

📝 需要测试Airflow集群吗？ 使用我们的配套项目 Airflow-Docker-Compose，支持Airflow 2.x 和 Airflow 3.x 环境！

快速入门/教程流程图

🎯 推荐：Docker Compose（完整的演示环境）

用于快速评估和测试：

git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API

# 配置您的Airflow凭证
cp .env.example .env
# 编辑.env文件以设置您的Airflow API设置

# 启动所有服务
docker-compose up -d

# 访问OpenWebUI http://localhost:3002/
# API文档 http://localhost:8002/docs

开始使用OpenWebUI（Docker选项）

访问 http://localhost:3002/
使用管理员账户登录
从顶部菜单进入“设置” → “工具”
添加工具URL：http://localhost:8002/airflow-api
配置您的LLM提供商（例如Ollama、OpenAI等）

📦 MCP服务器安装方法

方法1：直接从PyPI安装

uvx --python 3.12 mcp-airflow-api

方法2：Claude-Desktop MCP客户端集成

本地访问（stdio模式）

{
  "mcpServers": {
    "mcp-airflow-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v2",
        "AIRFLOW_API_BASE_URL": "http://localhost:8080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    }
  }
}

远程访问（无认证的streamable-http模式）

{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

远程访问（带Bearer令牌认证的streamable-http模式 - 推荐）

{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

不同版本的多个Airflow集群

{
  "mcpServers": {
    "airflow-2x-cluster": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-airflow-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v1",
        "AIRFLOW_API_BASE_URL": "http://localhost:38080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    },
    "airflow-3x-cluster": {
      "command": "uvx",
      "args": ["--python", "3.12", "m-空气流-api"],
      "env": {
        "AIRFLOW_API_VERSION": "v2",
        "AIRFLOW_API_BASE_URL": "http://localhost:48080/api",
        "AIRFLOW_API_USERNAME": "airflow",
        "AIRFLOW_API_PASSWORD": "airflow"
      }
    }
  }
}

💡 小贴士：使用来自 Airflow-Docker-Compose 的测试集群进行上述配置 - 它们分别在端口38080（2.x）和48080（3.x）上运行！

方法3：开发安装

git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API
pip install -e .

# 在stdio模式下运行
python -m mcp_airflow_api

🌟 关键特性

自然语言查询
不需要学习复杂的API语法。只需像自然说话一样询问：
- "哪些DAG目前在运行？"
- "显示失败的任务"
- "查找包含ETL的DAG"
全面监控能力
实时集群状态监控：
- 集群健康状况监控
- DAG状态和性能分析
- 任务执行日志跟踪
- XCom数据管理
动态API版本支持
单个MCP服务器适应您的Airflow版本：
- API v1：43个共享工具，兼容Airflow 2.x
- API v2：43个共享工具 + 2个资产管理工具，适用于Airflow 3.0+
- 环境变量控制：通过AIRFLOW_API_VERSION即时切换版本
- 零配置更改：相同的工具名称，增强的功能
- 高效架构：共享公共代码库消除重复
全面工具覆盖
覆盖几乎所有的Airflow API功能：
- DAG管理（触发、暂停、恢复）
- 任务实例监控
- 池和变量管理
- 连接配置
- 配置查询
- 事件日志分析
大型环境优化
高效处理具有1000+ DAG的大环境：
- 智能分页支持
- 高级过滤选项
- 批量处理能力

🛠️ 技术优势

利用模型上下文协议（MCP）
MCP是一种开放标准，用于AI应用程序与数据源之间的安全连接，提供：
- 标准化接口
- 安全的数据访问
- 可扩展架构
支持两种传输模式
- stdio模式：直接MCP客户端集成，适用于本地环境
- streamable-http模式：基于HTTP的部署，适用于Docker和远程访问
环境变量控制：
```
FASTMCP_TYPE=stdio          # 默认：直接MCP客户端模式
FASTMCP_TYPE=streamable-http # Docker/HTTP模式
FASTMCP_PORT=8000           # HTTP服务器端口（Docker内部）
```
全面的Airflow API覆盖
完整实现官方Airflow REST API：
- API v1支持：基于 Airflow 2.x REST API
- API v2支持：基于 Airflow 3.0+ REST API
- 动态版本选择：运行时在API版本之间切换
- 功能一致性：两个版本的完整端点覆盖
完整的Docker支持
完整的Docker Compose设置，包含3个独立的服务：
- Open WebUI：Web界面（端口 3002）
- MCP Server：Airflow API工具（内部端口 8000，通过 18002 暴露）
- MCPO Proxy：REST API端点提供者（端口 8002）

实际用例

运营团队容量管理

⚙️ 高级配置

环境变量

# 必需 - 动态API版本选择（新功能！）
# 单个服务器支持v1和v2 - 只需更改此变量即可！
AIRFLOW_API_VERSION=v1           # v1用于Airflow 2.x，v2用于Airflow 3.0+
AIRFLOW_API_BASE_URL=http://localhost:8080/api

# 测试集群连接示例：
# 对于Airflow 2.x测试集群（来自Airflow-Docker-Compose）
AIRFLOW_API_VERSION=v1
AIRFLOW_API_BASE_URL=http://localhost:38080/api

# 对于Airflow 3.x测试集群（来自Airflow-Docker-Compose）  
AIRFLOW_API_VERSION=v2
AIRFLOW_API_BASE_URL=http://localhost:48080/api

# 认证
AIRFLOW_API_USERNAME=airflow
AIRFLOW_API_PASSWORD=airflow

# 可选 - MCP服务器配置
MCP_LOG_LEVEL=INFO                   # DEBUG/INFO/WARNING/ERROR/CRITICAL
FASTMCP_TYPE=stdio                   # stdio/streamable-http
FASTMCP_PORT=8000                    # HTTP服务器端口（Docker模式）

# streamable-http模式的Bearer令牌认证
# 启用认证（生产推荐）
# 默认：false（未定义、空或null时）
# 值：true/false, 1/0, yes/no, on/off（不区分大小写）
REMOTE_AUTH_ENABLE=false             # true/false
REMOTE_SECRET_KEY=your-secure-secret-key-here

API版本比较

官方文档：

API v1：Airflow 2.x REST API参考
API v2：Airflow 3.0+ REST API参考

特性	API v1 (Airflow 2.x)	API v2 (Airflow 3.0+)
总工具数	43个工具	45个工具
共享工具	43（100%）	43（96%）
独有工具	0	2（资产管理）
基本DAG操作	✅	✅ 增强
任务管理	✅	✅ 增强
连接管理	✅	✅ 增强
池管理	✅	✅ 增强
资产管理	❌	✅ 新
资产事件	❌	✅ 新
数据感知调度	❌	✅ 新
增强的DAG警告	❌	✅ 新
高级过滤	基础	✅ 增强

🔐 安全与认证

Bearer令牌认证

对于streamable-http模式，此MCP服务器支持Bearer令牌认证以保护远程访问。这在生产环境中运行服务器时尤为重要。

配置

启用认证：

# 在.env文件中
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

或通过CLI：

python -m mcp_airflow_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

安全级别

stdio模式（默认）：仅限本地访问，无需认证
streamable-http + REMOTE_AUTH_ENABLE=false：无认证的远程访问 ⚠️ 不推荐用于生产
streamable-http + REMOTE_AUTH_ENABLE=true：带有Bearer令牌认证的远程访问 ✅ 推荐用于生产

注意：REMOTE_AUTH_ENABLE未定义、空或null时默认为false。支持的值是true/false，1/0，yes/no，on/off（不区分大小写）。

客户端配置

当启用认证时，MCP客户端必须在Authorization头中包含Bearer令牌：

{
  "mcpServers": {
    "mcp-airflow-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

安全最佳实践

始终启用认证 当在生产中使用streamable-http模式时
使用强随机生成的秘密密钥（建议32个字符以上）
使用HTTPS 如果可能（配置带有SSL/TLS的反向代理）
使用防火墙或网络策略限制网络访问
定期轮换秘密密钥 以增强安全性
监控访问日志 以防未经授权的访问尝试

错误处理

当认证失败时，服务器返回：

401 Unauthorized 对于缺失或无效的令牌
详细的错误消息 以JSON格式进行调试

自定义Docker Compose设置

version: '3.8'
services:
  mcp-server:
    build: 
      context: .
      dockerfile: Dockerfile.MCP-Server
    environment:
      - FASTMCP_PORT=8000
      - AIRFLOW_API_VERSION=v1
      - AIRFLOW_API_BASE_URL=http://your-airflow:8080/api
      - AIRFLOW_API_USERNAME=airflow
      - AIRFLOW_API_PASSWORD=airflow

开发安装

git clone https://github.com/call518/MCP-Airflow-API.git
cd MCP-Airflow-API