内容
# @us-all/airflow-mcp
> Airflow MCP 服务器 — 读取 DAGs、运行、任务实例、日志尾部；触发和清除（写入权限受限）。基于 `@us-all/mcp-toolkit` 构建。
一个专注于 Airflow 3.x REST API (`/api/v2`) 的 MCP 服务器。默认情况下为只读；`airflow-trigger-dag` 和 `airflow-clear-task` 需要在 `AIRFLOW_ALLOW_WRITE=true` 时才能使用。身份验证通过 SimpleAuthManager 使用 JWT — 需要提供 `AIRFLOW_USERNAME` 和 `AIRFLOW_PASSWORD`，服务器将透明地颁发和刷新令牌。
对于更深入的 dbt 集成（解析清单、运行结果历史、源新鲜度、每列测试覆盖率、血缘行走、自定义 DQ 结果表），请在旁边安装配套的 **[@us-all/dbt-mcp](https://www.npmjs.com/package/@us-all/dbt-mcp)**。
- `airflow` 和 `meta` 类别中有 7 种工具
- 2 个 MCP 提示用于 DAG 分类工作流
- 1 个聚合工具取代了 list-runs → get-task-instances 组合
## 安装
```bash
pnpm add -D @us-all/airflow-mcp
```
## 运行
```bash
AIRFLOW_API_URL=http://airflow.example.com:8080 \
AIRFLOW_USERNAME=admin AIRFLOW_PASSWORD=... \
npx @us-all/airflow-mcp
```
仅传递主机基地址 — 服务器在内部添加 `/api/v2` 前缀。如果提供，则会删除末尾的 `/api/v1` 或 `/api/v2`。JWT 令牌会在会话期间缓存，并在过期前 1 分钟刷新。
服务器使用 MCP stdio；将其连接到 Claude Desktop / Cursor / 任何 MCP 客户端。设置 `MCP_TRANSPORT=http` 以选择流式 HTTP 传输（Bearer 身份验证、`/health` 端点）。
## 工具
### `airflow`（6 + 1 个聚合工具）
| 工具 | 描述 |
|------|-------------|
| `airflow-list-dags` | 列出带有标签/搜索筛选器的活动 DAG |
| `airflow-list-runs` | 一个 DAG 的最近运行（状态筛选器，按最新运行排序） |
| `airflow-get-task-instances` | 特定 DAG 运行的任务实例 |
| `airflow-get-task-logs` | 一个任务实例日志的尾部（最后 N KB） |
| `airflow-trigger-dag` | 触发新的运行（写入权限受限） |
| `airflow-clear-task` | 清除特定的任务实例 → 重新运行（写入权限受限） |
| `dag-health-rollup` | 集成的 DAG 健康状况：成功率 + 平均持续时间 + 最后一次失败运行 + 失败任务 |
### `meta`
`search-tools` — 自然语言工具发现。
### 提示
| 提示 | 使用场景 |
|--------|----------|
| `dag-failure-triage` | "为什么 DAG X 失败了？" — 拉取运行，隔离失败，导出日志，建议补救措施 |
| `dag-schedule-audit` | "扫描所有 DAG 以查找低成功率和卡住的运行" |
## 环境变量
| 环境变量 | 是否必需 | 备注 |
|-----|----------|-------|
| `AIRFLOW_API_URL` | 是 | Airflow 主机基地址，例如 `http://airflow.example.com:8080`。如果存在，则会删除末尾的 `/api/v1` 或 `/api/v2` |
| `AIRFLOW_USERNAME` | 是 | 用于 SimpleAuthManager `/auth/token` 的 JWT 颁发用户名 |
| `AIRFLOW_PASSWORD` | 是 | 用于 JWT 颁发的密码（密钥） |
| `AIRFLOW_ALLOW_WRITE` | 否 | `true` 启用 `airflow-trigger-dag` / `airflow-clear-task` |
| `AIRFLOW_TOOLS` / `AIRFLOW_DISABLE` | 否 | 类别切换 |
## 测试验证的架构
- Airflow 3.0–3.2 `/api/v2`（已针对 3.2.1 验证，这是截至 2026-05 的当前 Airflow 版本）。Airflow 2.x 不受 v0.2+ 支持，因为基本身份验证 + `/api/v1` 已被删除；对于 Airflow 2.x 部署，请固定到 `@us-all/airflow-mcp@0.1.0`。
## 配套服务器
对于 dbt 工件解析、运行结果历史和 DQ 结果表，请在旁边安装 [`@us-all/dbt-mcp`](https://www.npmjs.com/package/@us-all/dbt-mcp)。
## 构建
```bash
pnpm install
pnpm run build # tsc → dist/
pnpm test # vitest
pnpm run smoke # 启动 dist/index.js，调用 initialize + tools/list（请先设置环境变量）
```
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
