astronomer/agents: An MCP Server and Skills Bundle for Airflow Workflows

The Gap astronomer/agents Fills Between an Agent and a Running Airflow Instance

An agent asked to debug a failing DAG has no way to see the scheduler. It can read the DAG file in your repository, but task instance state, retry counts and worker logs live behind the Airflow REST API, and pasting those into a chat window by hand is the workflow this repository is trying to remove. The MCP server wraps that REST API as tools an agent can call. The README describes it as full Airflow REST API integration covering DAG management, triggering, task logs and system health. The audience is narrow and specific: data engineers whose pipelines are already orchestrated by Airflow and who use an agentic coding tool such as Claude Code or Cursor alongside their editor. If you write SQL against a warehouse but never touch a scheduler, the Airflow half of this repository has nothing for you, though the warehouse skills might.

MCP Server, Skills and the af CLI: Three Separate Mechanisms

The repository ships three things that are easy to conflate. The first is astro-airflow-mcp, a Python package published to PyPI and run locally, typically through uvx. It speaks the Model Context Protocol over stdio, so the client launches it as a subprocess and exchanges tool calls. The second is a set of skills, which are directories of instructions and scripts that an agent reads on demand; the README lists them under headings such as Data Discovery and Analysis, Data Lineage and DAG Development, with names like warehouse-init, analyzing-data, checking-freshness and authoring-dags. The third is the af CLI, documented inside the astro-airflow-mcp README, for interacting with Airflow from a terminal without an agent in the loop. The data flow differs by component. The MCP server is stateless request and response against your Airflow instance. The analyzing-data skill is not: the README states it uses a background Jupyter kernel for SQL-based analysis, which is why the Cursor setup includes a stop hook that runs `uv run $CURSOR_PROJECT_DIR/.cursor/skills/analyzing-data/scripts/cli.py stop` with a ten second timeout to clean up the kernel when the session ends. That hook is the clearest signal of where state actually lives in this design.

Installation Paths and the Configuration Keys That Matter

There are three installation routes and they are not equivalent. The generic route is `npx skills add astronomer/agents --skill '*'`, which installs every skill through skills.sh and prompts for which agents to target. Omitting `--skill` lets you select skills individually. For Cursor specifically, `npx skills add astronomer/agents --skill '*' -a cursor` writes into `.cursor/skills/`. Claude Code gets a different treatment: the README recommends the plugin over the skills installer for better integration with MCP servers and hooks, installed with `claude plugin marketplace add astronomer/agents` followed by `claude plugin install astronomer-data@astronomer`. The README also notes an upgrade path for anyone on the old plugin name, requiring `claude plugin uninstall data@astronomer` before reinstalling. For clients outside those two, you register the server manually. The Cursor example writes to `~/.cursor/mcp.json` with a command of `uvx`, args of `["astro-airflow-mcp", "--transport", "stdio"]`, and a server key of `airflow`. Pointing at a remote instance adds three environment variables: AIRFLOW_API_URL, AIRFLOW_USERNAME and AIRFLOW_PASSWORD. The README states the MCP server works with any Airflow 2.x or 3.x REST API and that self-hosted users should set AIRFLOW_API_URL to their own instance. Note the password is passed as an environment variable in the documented example, which is fine for a local trial and worth reconsidering for anything shared.

Where the Repository Stops Short

The README's skill table is truncated mid-sentence at the blueprint entry, described as composing DAGs from YAML using reusable templates with Pyda, with the sentence cut off. That means the full skill inventory cannot be confirmed from the supplied material. The troubleshooting and roadmap sections appear in the table of contents but their contents are not included, so there is no way to say what failure modes the maintainers already know about. Two design points are worth flagging on their own. The MCP server is launched fresh per client session through uvx, which pulls from PyPI; that means an offline or air-gapped workstation needs a different distribution path than the one documented. And the analyzing-data skill depends on a Jupyter kernel surviving between agent turns, which is exactly the kind of background process that leaks when a client crashes rather than exits cleanly. The stop hook exists because of that, and hooks are configured per client, so a client without hook support leaves the kernel running.

How This Differs From an Airflow Provider or a Plain REST Client

The obvious alternative is to skip the agent layer and call the Airflow REST API yourself, or use the Airflow Python client. That approach gives you typed responses, retries you control and no dependency on an agent's tool-calling accuracy. The difference in approach is who decides which call to make. A REST client executes a sequence you wrote in advance; the MCP server exposes the API surface as tools and lets the model choose, which is the entire point and also the entire risk. If you already know you want the logs for task X in run Y, a twenty-line script is more predictable than any agent. The MCP server earns its place when the sequence is not known up front, for instance when you are asking what broke and the answer requires walking from a failed DAG run to a specific task instance to its logs. The skills layer sits further toward convenience: tracing-downstream-lineage and tracing-upstream-lineage encode lineage analysis as instructions rather than as a library you import, which means their behaviour depends on the agent reading them carefully. There is no compiled artifact to test.

Versioning, Licensing and What Upgrades Actually Cost

The repository is Apache-2.0 licensed and the README states it is compatible with open-source Apache Airflow, so there is no separation between an Astro-hosted tier and the code here. The MCP server is versioned independently of the repository: the most recent releases listed are astro-airflow-mcp 0.9.1 from July 2026, 0.9.0 from late June 2026, and 0.8.2 from May 2026. That cadence, roughly monthly with a patch in between, is the upgrade cost you are signing up for if you pin the package. Because the documented launch path is `uvx astro-airflow-mcp` with no version pin, a default install tracks the latest release; adding a version constraint to the args array is the way to stop that. Skills are the softer dependency. They are files copied into your project under `.cursor/skills/` or the equivalent, so updating them means re-running the installer, and any local edits you made will conflict. The Apache-2.0 licence permits commercial use and modification; it also means no warranty, and since the MCP server can trigger DAG runs and read task logs, the credentials you give it define the blast radius. Scope the Airflow user accordingly rather than reusing an admin account.

Who Should Install This and What to Check First

The fit is a team running Airflow 2.x or 3.x, using Claude Code or Cursor, and already comfortable with an agent reading and writing files in the repository. For that team the plugin route is the shortest path, and the MCP server alone is worth trying even if you ignore the skills. The misfit is anyone whose orchestration is not Airflow. The README is explicit that the MCP server targets the Airflow REST API and that skills are tool-agnostic across Airflow deployments, which is a narrower claim than tool-agnostic across orchestrators. If you run dbt without Airflow, the warehouse skills may still apply, but the lineage and DAG authoring skills assume Airflow task graphs. Before committing, confirm the REST API endpoint answers from the machine that will run uvx, set the three environment variables against a non-production instance, and check the repository's skills directory directly rather than relying on the README table, which is incomplete as published.

Editorial conclusion

Adopt astronomer/agents if your DAGs already run on Airflow 2.x or 3.x and you want an agent to read task logs, trigger runs and trace lineage through the REST API rather than through copy-pasted context. Do not adopt it if your orchestration is Dagster, Prefect or plain cron, because every skill in the repository assumes Airflow primitives. Before installing, verify three things: that your Airflow REST API is reachable from the machine running the MCP server, that AIRFLOW_API_URL, AIRFLOW_USERNAME and AIRFLOW_PASSWORD are set for your instance, and that the skills directory contains the specific skill you need, since the README's skill list is truncated mid-entry at blueprint.

Frequently asked questions

Official sources

1. astronomer/agents on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases