Incident Response MCP for Apache Airflow

Apache Airflow MCP 服务

独立的社区项目；与 Apache Software Foundation 无关联，也未获其认可。

通过 PyPI、 GHCR 和官方 MCP 注册表发布。 每个不可变版本均附有可复现的扫描报告、依赖审计、SBOM 和来源证明。

将 Claude、Cursor、VS Code 或其他 MCP 客户端连接到 Apache Airflow 部署，帮助 Agent 诊断失败的 DAG。

粘贴来自 PagerDuty/Datadog 告警的 Airflow UI 链接，然后询问 “为什么失败了？”——Agent 会解析 URL、查找失败的任务、提取经过筛选并限制在 MCP 响应范围内的日志错误，还能重新触发或清除运行。写入工具带有破坏性操作注解，MCP 客户端可据此请求确认。

亮点

• 🔍 以事件响应为先 — 直接从 Airflow UI URL 定位失败任务，按错误级别筛选日志并提供上下文行，正确遵循 try_number 语义（包括传感器）
• 🏢 多实例 — 一台服务可连接同一 API 系列的开发/预发布/生产环境目标，支持每个实例使用不同凭据，并配备拒绝未知主机的 SSRF 防护
• 🔒 安全控制 — 可选择启用只读模式（AIRFLOW_MCP_READ_ONLY=true），此模式绝不注册写入工具；写入工具标注为破坏性操作；实例响应和操作日志中会遮蔽已配置的凭据
• 📉 节省令牌 — 日志尾部读取、级别筛选、字节数上限和截断元数据，专为大模型上下文窗口设计
• 🧭 Airflow 2 和 3 — 提供 API v1/v2 适配器，并针对 Airflow 2.11 和 3.3 进行实时 E2E 测试，包括 JWT 身份验证
• 📎 可追踪 — 每个响应都包含一个与结构化服务日志对应的 request_id

快速开始

1. 安装

uv tool install apache-airflow-mcp-server \
  --with 'apache-airflow-client==3.3.0'  # replace 3.3.0 with your Airflow version

使用 Airflow 2.11？ 请改用 --with 'apache-airflow-client==2.10.0'；2.10.0 是最后一个生成的 v1 客户端，面向 Airflow 2 的稳定 API。使用其他版本前，请参阅 Airflow 兼容性。

2. 连接 MCP 客户端

最快的方式是使用环境变量配置单个实例——无需配置文件。

claude mcp add airflow \
  --env AIRFLOW_MCP_HOST=https://airflow.example.com \
  --env AIRFLOW_MCP_USERNAME=admin \
  --env AIRFLOW_MCP_PASSWORD=your-password \
  --env AIRFLOW_MCP_READ_ONLY=true \
  -- uvx --from apache-airflow-mcp-server \
  --with apache-airflow-client==3.3.0 airflow-mcp --transport stdio

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

{
  "servers": {
    "airflow": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
      "env": {
        "AIRFLOW_MCP_HOST": "https://airflow.example.com",
        "AIRFLOW_MCP_USERNAME": "admin",
        "AIRFLOW_MCP_PASSWORD": "your-password",
        "AIRFLOW_MCP_READ_ONLY": "true"
      }
    }
  }
}

AIRFLOW_MCP_HOST=https://airflow.example.com \
AIRFLOW_MCP_USERNAME=admin AIRFLOW_MCP_PASSWORD=your-password \
AIRFLOW_MCP_READ_ONLY=true \
airflow-mcp --transport http --host 127.0.0.1 --port 8765

{ "mcpServers": { "airflow": { "url": "http://127.0.0.1:8765/mcp" } } }

3. 向你的 Agent 提问

"etl_pipeline 最近一次运行为什么失败了？"

"https://airflow.example.com/dags/etl_pipeline/grid — 这里发生了什么？清除它安全吗？"

"显示失败任务的错误上下文，并告诉我最小的恢复操作。"

Airflow 兼容性

该服务通过生成的 apache-airflow-client 与 Airflow 通信。 对于 Airflow 3，请让客户端版本与 Airflow 版本匹配：生成的模型在同一主版本内也可能变化，较新的客户端不一定能正确反序列化较旧服务的响应。Airflow 2.11 使用最终版 v1 客户端 2.10.0，通过 Airflow 2 的稳定 API 通信。

如果未设置 api_version，服务会假定使用与已安装客户端相匹配的 API（2.x 客户端使用 v1，3.x 客户端使用 v2）。请显式设置 AIRFLOW_MCP_API_VERSION（或在注册表中设置 api_version:），以便尽早发现主版本不匹配。

目前，单个服务进程只能加载一个生成的客户端主版本。因此，注册表中的所有实例都必须使用相同的 API 系列；请为 Airflow 2 和 Airflow 3 分别运行 MCP 服务进程。混合版本支持需要未来更改客户端适配器，目前尚未宣称可用。

Airflow 3 说明：

• 认证：Bearer 令牌会作为 JWT 直接传递；基本凭据会自动通过 POST /auth/token 交换为 JWT，并定期刷新（AIRFLOW_MCP_TOKEN_REFRESH_SECONDS，默认值为 3600——请确保它小于部署环境中的 JWT 过期时间，并注意目前 401 响应不会触发自动重新认证）。
• execution_date 排序会映射到 logical_date，数据集会映射到资产，UI 链接会使用 Airflow 3 的路由方案。工具名称和核心工作流保持稳定；文档中说明的字段和选项可能因 API 系列而异。
• 对于 Airflow 3 中已不存在的清除选项（include_subdags/include_parentdag，以及 airflow_clear_dag_run 的 include_*/reset_dag_runs 选项），服务会返回 INVALID_INPUT，而不会默默缩小破坏性操作的范围。

我们会在相关的拉取请求和 main 推送中测试这两类客户端。非常欢迎提交来自真实 Airflow 部署环境的错误报告！

配置

单实例（仅环境变量）

* 提供用户名和密码，或令牌。

多实例（注册表 YAML）

将 AIRFLOW_MCP_INSTANCES_FILE 指向一个 YAML 注册表（其优先级高于单实例环境变量）。值可以通过 ${VAR} 引用环境变量：

data-stg:
  host: https://airflow.data-stg.example.com/
  api_version: v1        # Airflow 2
  verify_ssl: true
  auth:
    type: basic
    username: ${AIRFLOW_DATA_STG_USERNAME}
    password: ${AIRFLOW_DATA_STG_PASSWORD}

data-prod:
  host: https://airflow.data-prod.example.com/
  api_version: v1        # Keep one client/API family per server process
  auth:
    type: bearer
    token: ${AIRFLOW_DATA_PROD_TOKEN}

每个工具都接受 instance 键（data-stg）或 ui_url——一个完整的 http(s) Airflow UI URL，其主机将与注册表进行匹配；未知主机将被拒绝（SSRF 防护）。如果链接中包含 dag_id/dag_run_id/task_id，ui_url 也会自动填充这些字段。如果同时传入 instance 和 ui_url，但两者不一致，调用将以 INSTANCE_MISMATCH 失败，而不会猜测。

Kubernetes 提示： 将注册表从 Secret 挂载到 /config/instances.yaml，并设置 AIRFLOW_MCP_INSTANCES_FILE=/config/instances.yaml。

服务选项

只读模式

快速入门配置会设置 AIRFLOW_MCP_READ_ONLY=true：不会注册写入工具（触发、清除、暂停/取消暂停）。这可以防止 MCP 执行变更，但读取工具仍可能泄露敏感日志、配置、渲染后的字段和 DAG 运行数据；请使用遵循最小权限原则的 Airflow 凭据。

如需有意启用恢复操作，请设置 AIRFLOW_MCP_READ_ONLY=false。此时，写入工具会携带 MCP destructiveHint 注释，客户端可在决定是否请求确认时使用这些注释。注释仅供参考，因此只有在 Airflow 凭据和 MCP 客户端的审批行为适合目标环境时，才应启用写入操作。

工具

发现和 URL 实用工具

读取

写入（标注为具有破坏性，因此客户端可以要求审批；在只读模式下完全隐藏）

每个成功载荷都包含用于关联日志的 request_id；失败时会抛出包含 {code, message, request_id, context} 的结构化 ToolError。

事故处理工作流

这些工具正是围绕这一流程设计的——通过四次调用，从告警链接找到诊断结果：

# 1. Alert contains an Airflow UI link → resolve it
airflow_resolve_url("https://airflow.example.com/dags/etl_pipeline/grid?dag_run_id=...")
#    → {instance, dag_id, dag_run_id, ...}

# 2. Which tasks failed in this run?
airflow_list_task_instances(dag_id="etl_pipeline", dag_run_id="scheduled__2026-01-01",
                            state=["failed"])

# 3. Get attempt metadata (authoritative try_number, retries, timings)
ti = airflow_get_task_instance(dag_id="etl_pipeline",
                               dag_run_id="scheduled__2026-01-01",
                               task_id="transform_data")

# 4. Pull only the error lines, with context, capped for the LLM
airflow_get_task_instance_logs(dag_id="etl_pipeline",
                               dag_run_id="scheduled__2026-01-01",
                               task_id="transform_data",
                               try_number=ti["attempts"]["try_number"],
                               tail_lines=500, filter_level="error", context_lines=5)

日志响应包含 truncated、auto_tailed（超过 100 MB 的日志会自动读取尾部）、match_count 以及字节数/行数统计，因此 Agent 能准确了解自己查看的内容。按主机分段的日志会使用 --- [worker-1] --- 标头合并；Airflow 3 结构化日志则会渲染为纯文本行。

关于 try_number 的说明： 在 Airflow 2.9 中，重新调度模式的传感器可能会在每次重新调度时递增该值；Airflow 2.10 及更高版本不再如此。请始终从 airflow_get_task_instance 读取该值，不要猜测——派生字段 retries_consumed / retries_remaining 只是启发式估算。

部署

Docker

docker run -p 127.0.0.1:8765:8765 \
  -e AIRFLOW_MCP_HOST=https://airflow.example.com \
  -e AIRFLOW_MCP_USERNAME=admin \
  -e AIRFLOW_MCP_PASSWORD=your-password \
  -e AIRFLOW_MCP_READ_ONLY=true \
  ghcr.io/madamak/apache-airflow-mcp-server:latest

或者，在本地使用 docker build -t airflow-mcp . 构建

发布镜像包含锁文件指定的 Airflow 3.3 客户端，并在 :8765 上提供可流式传输的 HTTP 服务（/mcp 端点，/health 用于探测）。MCP HTTP 端点没有内置调用方身份验证：请仅绑定到环回地址，或将其置于经过身份验证的私有代理后方。对于多实例部署，请挂载属于同一 API 系列的 registry YAML。在发布单独的 v1 镜像之前，Airflow 2 部署应使用上述固定版本的本地安装路径。

CI 会审计精确镜像中安装的 Python 依赖项，并使用固定版本的 Cisco MCP Scanner 发布版中的 YARA 分析器扫描只读和启用写入的 MCP 工具表面。若扫描不完整或存在任何尚未分类的 YARA 发现，安全工作流就会失败。从 v1.0.1 开始，发布资源包含机器可读的扫描报告，发布镜像清单则附带涵盖更广泛软件包清单的 SBOM 和来源证明。这些是自动化检查，并非安全认证，也不能替代针对具体部署的审查。

FastMCP 工具

此处包含 fastmcp.json，方便支持 FastMCP 的工具自动发现入口点和部署默认值。

开发

uv sync                 # install dependencies
uv run pytest           # unit tests (no real network; the Airflow client is mocked)
uv run ruff check .     # lint
uv run ruff format .    # format
uv run airflow-mcp --transport stdio   # run locally
./scripts/e2e.sh af2    # end-to-end against Airflow 2.11
./scripts/e2e.sh af3    # end-to-end against Airflow 3.3
                        # Both seed failures/noisy logs and drive every tool
                        # through MCP. Set E2E_KEEP=1 to keep the instance up.

CI 会在 Python 3.10–3.13 上，针对 apache-airflow-client 的两个系列运行单元测试套件。相关拉取请求、推送到 main、每夜运行和发布还会使用 Docker 化的 Airflow 2.11 和 3.3 进行实时测试。指南请参阅 CONTRIBUTING.md；如果要让编码 Agent 使用此代码库，请参阅 AGENTS.md（该文件就是为此编写的）。

贡献

欢迎提交问题和 PR，尤其是：

• 真实 Airflow 事故响应工作流和版本组合的报告
• 对有限日志、安全诊断和优先使用 URL 的工作流的改进
• 更多 MCP 主机和部署类型的客户端配置指南

如果这个服务帮你省下了一次调试，点个 ⭐ 就能帮助其他 Airflow 团队找到它。

许可证

Apache 2.0——请参阅 LICENSE。

Apache Airflow 和 Airflow 是 Apache 软件基金会的注册商标。本独立项目与 ASF 无关，也未获得 ASF 背书。