# airflow-mcp-server

An MCP server that lets Claude inspect and operate **Apache Airflow** over its
REST API. It exposes safe, curated tools (read + a few guarded writes) rather
than mirroring the whole API.

Targets **Airflow 2** (stable REST API `/api/v1`). Airflow 3 is intentionally
out of scope.

Runs as a local stdio server: each user runs it on their own machine with their
own Airflow credentials, which keeps Airflow RBAC intact.

## Status

Working read and write tools against Airflow 2; not yet published.

**Read:** `get_airflow_version`, `get_airflow_health`, `list_pools`,
`list_dags`, `get_dag`, `list_dag_runs`, `get_dag_run`, `list_task_instances`,
`get_task_instance`, `get_task_logs`, `list_import_errors`.

**Write** (refused when `AIRFLOW_MCP_READ_ONLY=true`): `trigger_dag_run`,
`set_dag_paused`, `clear_task_instances` (supports `dry_run` to preview, and
reopens a finished DAG run by default so cleared tasks actually get scheduled).

## Configuration

All settings come from `AIRFLOW_MCP_*` environment variables (prefixed to avoid
clashing with Airflow's own env). See [`.env.example`](.env.example).

| Variable | Required | Default | Notes |
| --- | --- | --- | --- |
| `AIRFLOW_MCP_BASE_URL` | yes | - | e.g. `http://localhost:8080` (no `/api` suffix) |
| `AIRFLOW_MCP_USERNAME` / `AIRFLOW_MCP_PASSWORD` | one auth method | - | Basic auth |
| `AIRFLOW_MCP_API_TOKEN` | one auth method | - | Bearer token; wins over basic auth |
| `AIRFLOW_MCP_READ_ONLY` | no | `false` | `true` disables every write tool |
| `AIRFLOW_MCP_VERIFY_SSL` | no | `true` | |
| `AIRFLOW_MCP_TIMEOUT` | no | `30` | seconds |

## Use with Claude

Run it straight from GitHub - no clone needed (`uvx` fetches and runs it):

```json
{
  "mcpServers": {
    "airflow": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ssasuoirafen/airflow-mcp-server",
        "airflow-mcp"
      ],
      "env": {
        "AIRFLOW_MCP_BASE_URL": "http://localhost:8080",
        "AIRFLOW_MCP_USERNAME": "airflow",
        "AIRFLOW_MCP_PASSWORD": "airflow"
      }
    }
  }
}
```

Pin a version by appending a ref, e.g. `git+https://github.com/ssasuoirafen/airflow-mcp-server@v0.1.0`.

For local development, point at a checkout instead:

```json
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\airflow-mcp-server", "airflow-mcp"]
```

The package also installs an `airflow-mcp-server` executable (same thing) for the longer name.

If published to PyPI later, this simplifies to `"command": "uvx", "args": ["airflow-mcp"]`.

## Development

```bash
uv sync                # install deps
uv run pytest          # unit tests (mocked, no network)
uv run pytest -m e2e   # opt-in live test; needs a .env pointing at a real Airflow 2
uv run airflow-mcp          # run the server (expects an MCP client on stdio)
```

## Roadmap

1. Foundation + connectivity (version, health). **done**
2. Read tools: DAGs, DAG runs, task instances, logs, import errors, pools. **done**
3. Safe writes: trigger DAG, pause/unpause, clear/retry tasks (gated by read-only). **done**
4. Packaging metadata and LICENSE. **done**
5. Publish to PyPI. *pending*

## License

MIT - see [LICENSE](LICENSE).