# airflow-dev-mcp

This is an [MCP](https://modelcontextprotocol.io) server for driving a local or development
Airflow cluster from an AI coding assistant such as Claude Code, Cursor, or any other
MCP client. Use it to trigger DAG runs, watch their status, read task logs, and see why
a DAG failed to parse, all without leaving your editor.

The server talks to Airflow through its REST API and nothing else. It never touches your
DAG source, filesystem, or database, and there are no config files to manage; everything
is set with environment variables. Both Airflow 3 (`/api/v2`) and Airflow 2 (`/api/v1`)
work, and the version is detected automatically.

## Configuring your MCP client

### Claude Code

The quickest way is `claude mcp add`, run from your project directory:

```bash
claude mcp add airflow-dev \
  -e AIRFLOW_URL=http://localhost:8080 \
  -e AIRFLOW_USERNAME=admin \
  -e AIRFLOW_PASSWORD=admin \
  -- uvx airflow-dev-mcp
```

Add `--scope user` to make it available in every project, or `--scope project` to write a
`.mcp.json` you can commit for your team. The default scope is local to you in the current
project.

#### Manual configuration
To set it up by hand instead, put the following in a `.mcp.json` file at your project root:

```json
{
  "mcpServers": {
    "airflow-dev": {
      "command": "uvx",
      "args": ["airflow-dev-mcp"],
      "env": {
        "AIRFLOW_URL": "http://localhost:8080",
        "AIRFLOW_USERNAME": "admin",
        "AIRFLOW_PASSWORD": "admin"
      }
    }
  }
}
```

For a setup that applies everywhere, put the same `mcpServers` block in `~/.claude.json`.

### Other clients

Any client that launches stdio MCP servers works the same way. Have it run
`uvx airflow-dev-mcp` (or `airflow-dev-mcp` if you installed it) with the environment
variables below.

## Configuration

| Variable | Default | Description |
| --- | --- | --- |
| `AIRFLOW_URL` | `http://localhost:8080` | Base URL of the cluster, with no path. |
| `AIRFLOW_USERNAME` | — | Username, used together with `AIRFLOW_PASSWORD`. |
| `AIRFLOW_PASSWORD` | — | Password. |
| `AIRFLOW_TIMEOUT` | `30` | HTTP timeout, in seconds. |
| `AIRFLOW_VERIFY_SSL` | `true` | Set to `false` to skip TLS verification for self-signed dev certs. |

Set `AIRFLOW_USERNAME` and `AIRFLOW_PASSWORD` and you are done; the server works out
whether it is talking to Airflow 3 or Airflow 2 on first use and authenticates the right
way.

## Tools

| Tool | What it does |
| --- | --- |
| `list_dags` | List registered DAGs with their paused, active, and import-error flags. |
| `get_import_errors` | Show parse failures with filename and traceback, so you can see why a new DAG isn't showing up. |
| `set_dag_paused` | Pause or unpause a DAG. New local DAGs start paused. |
| `trigger_dag` | Start a manual DAG run, optionally with a `conf` payload. Returns the `dag_run_id`. |
| `get_run_status` | Report a run's state and its per-task states (task, state, try number, operator, timing). |
| `get_task_logs` | Return the logs for one task attempt, tailed to the last N lines by default. |
| `list_dag_runs` | List recent runs of a DAG, to find a run when you don't have its id. |
| `clear_task_instances` | Clear tasks so they re-run. Previews as a dry run by default. |
| `list_variables` | Read Airflow Variables. |
| `list_connections` | Read Airflow Connections, with passwords omitted. |

Only `trigger_dag`, `set_dag_paused`, and `clear_task_instances` change anything on the
cluster; everything else is read-only. There are no tools that create or modify Variables
or Connections.

## License

MIT, see [LICENSE](LICENSE).

## Contributing

If you are interested in contributing see: [CONTRIBUTING.md](CONTRIBUTING.md).