Astronomer agents plugin
Astronomer plugin for data engineers: an Airflow MCP server, the af CLI and skills for DAGs, lineage and warehouse queries
- 461 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The server triggers DAGs, pauses them and permanently deletes runs, and the `warehouse.yml` settings give the agent access to the data warehouse.
- The analysis skill executes arbitrary SQL in a background Jupyter kernel using stored credentials.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/astronomer-agentsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The server triggers DAGs, pauses them and permanently deletes runs, and the `warehouse.yml` settings give the agent access to the data warehouse.
- The analysis skill executes arbitrary SQL in a background Jupyter kernel using stored credentials.
This is third-party code. Review the repository files before installing.
What it does
Astronomer agents is the Astronomer company repository with a toolset for an agent working with Apache Airflow and data warehouses. The `astronomer-data` plugin for Claude Code bundles the `astro-airflow-mcp` MCP server, the `af` command-line utility and more than 30 skills. The server runs through `uvx` and covers the Airflow 2 and 3 REST API: DAG lists and sources, triggering and awaiting runs, task logs, pauses and system health. The skills follow scenarios. For development they cover writing and validating DAGs, local testing, debugging failures, deployment, migrating from Airflow 2 to 3 and running dbt through Cosmos. For data they cover initializing the warehouse schema in `.astro/warehouse.md`, SQL analysis through a background Jupyter kernel, table profiling and freshness checks. A separate block is about lineage: skills trace where data came from and what breaks on a change, and build OpenLineage extractors.
Who it is for. Data engineers on Apache Airflow who hand Claude Code or Cursor the writing of DAGs, triage of failed runs and answers to warehouse questions.
Good fit when
- A nightly DAG failed, and the agent finds the cause from task logs and the source, then describes the fix.
- An Airflow 2 project moves to Airflow 3, and the migration skill walks through DAGs and flags incompatible spots.
- A dbt project runs as a set of Airflow tasks through Cosmos.
- An analyst asks how many customers arrived this week, and the agent finds the tables from the schema cache and runs the SQL.
Not a fit when
- Orchestration is built on another tool such as Dagster: the plugin only has a skill for migrating from there.
- The agent must not reach a production Airflow: the server can trigger, pause and delete runs.
- A plain warehouse query is needed without Airflow: a separate MCP for your database is simpler.
Example request
Look at the latest failed run of the load_orders DAG, find the cause in the task logs and show the source line that needs fixing.Limitations
The server needs `uv` and Python 3.10 or newer. A remote Airflow is set through `AIRFLOW_API_URL` plus a username and password or an `AIRFLOW_AUTH_TOKEN` token. Connections to Snowflake, Postgres, BigQuery and other warehouses are described in `~/.astro/agents/warehouse.yml`, and secrets go into `~/.astro/agents/.env`. The `setting-up-astro-project` and `managing-astro-local-env` skills belong to the Astro platform, and for open source Airflow the author advises Docker Compose and Helm. The `af` utility collects anonymous statistics with command names and is switched off with `af telemetry disable`. The repository holds more skills than the README lists.
How to disable. Run `claude plugin uninstall astronomer-data@astronomer`. Remove the server from the Cursor and other client configurations by hand. The `.astro/warehouse.md` file and the `~/.astro/agents/` settings stay on disk and are deleted separately.
FAQ
How do I install the plugin in Claude Code?
Run `claude plugin marketplace add astronomer/agents`, then `claude plugin install astronomer-data@astronomer`. If you installed the old `data@astronomer` plugin, remove it first with `claude plugin uninstall data@astronomer`.
How do I connect the Airflow server to Cursor or VS Code?
Add a server to `~/.cursor/mcp.json` or `.vscode/mcp.json` with the command `uvx` and the arguments `astro-airflow-mcp`, `--transport`, `stdio`. Cursor also has a quick install link.
Does the server work with a self-hosted Airflow?
Yes, any Airflow 2.x or 3.x with a REST API fits. Set the address in `AIRFLOW_API_URL` and the credentials in `AIRFLOW_USERNAME` and `AIRFLOW_PASSWORD`, or a token in `AIRFLOW_AUTH_TOKEN`.
Can the agent be barred from writing?
Yes, `AF_READ_ONLY=true` blocks all write operations. The set of available tools is narrowed with the `ASTRO_MCP_ALLOWED_TOOLS` variable, for example to `list_dags` and `get_dag_run`.
Where do I start with the warehouse?
With `/astronomer-data:warehouse-init`: the skill walks the databases from `warehouse.yml` and writes the schema into `.astro/warehouse.md`. After that `analyzing-data` answers faster because it does not search for tables anew.
Discussion
No questions or reviews yet.
Related
PluginsThe official Dagster kit for agents: a reference for assets and dg commands plus access to runs, logs and alerts in the cloud.
The Airbyte MCP connects an agent to an Airbyte organization: pipelines, syncs, job logs and direct data reads.
A plugin that connects an agent to a data warehouse and finds table, dbt model and semantic object metadata in the AGENTS schema.
An open-source agent for data engineers: a terminal SQL client with warehouse context, a semantic layer, REST and an MCP server.
A Google Cloud plugin catalog for databases and analytics: AlloyDB, Spanner, Bigtable, Firestore, Cloud SQL and Looker.
Claude Code plugins from the Oracle AI Data Platform team: Ask AIDP drives the Workbench through 43 MCP tools and aidp-cli.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Astronomer agents (this card) | yes | 461 | ||
| dbt Agent Skills | yes | 762 | official dbt Labs skills about dbt projects; this one centers on Airflow: a server, the `af` utility and DAG skills, with a Cosmos skill covering dbt | |
| dbt MCP | yes | API key | 621 | the official dbt Labs MCP server with the Semantic Layer and dbt command runs; this one is an Airflow MCP server and DAG work |
README in short
The documentation describes two paths for a data engineer: data analysis from warehouse initialization to freshness checks, and DAG development from project creation to debugging. The server can run standalone or as a plugin inside Airflow 2.
README badge
Original SKILL.md
---
name: analyzing-data
description: Queries the data warehouse with SQL and answers business questions about data. Use when answering anything that needs warehouse data - counts, metrics, trends, aggregations, joins across tables, data lookups, or ad-hoc SQL analysis (for example "who uses X", "how many Y", "show me Z", "find customers", "what is the count").
---
# Data Analysis
Answer business questions by querying the data warehouse. The kernel auto-starts on first `exec` call.
**All CLI commands below are relative to this skill's directory.** Before running any `scripts/cli.py` command, `cd` to the directory containing this file.
## Workflow
1. **Pattern lookup** — Check for a cached query strategy:
```bash
uv run scripts/cli.py pattern lookup "<user's question>"
```
If a pattern exists, follow its strategy. Record the outcome after executing:
```bash
uv run scripts/cli.py pattern record <name> --success # or --failure
```
2. **Concept lookup** — Find known table mappings:
```bash
uv run scripts/cli.py concept lookup <concept>
```
3. **Table discovery** — If cache misses, search the codebase (`Grep pattern="<concept>" glob="**/*.sql"`) or query `INFORMATION_SCHEMA`. See [reference/discovery-warehouse.md](reference/discovery-warehouse.md).
4. **Execute query**:
```bash
uv run scripts/cli.py exec "df = run_sql('SELECT ...')"
uv run scripts/cli.py exec "print(df)"
```
5. **Cache learnings** — Always cache before presenting results:
```bash
# Cache concept → table mapping
uv run scripts/cli.py concept learn <concept> <TABLE> -k <KEY_COL>
# Cache query strategy (if discovery was needed)
uv run scripts/cli.py pattern learn <name> -q "question" -s "step" -t "TABLE" -g "gotcha"
```
6. **Present findings** to user.