MCP-Airflow-API
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AIRFLOW_API_URL | Yes | The base URL of your Airflow REST API endpoint | |
| MCP_SERVER_PORT | No | Controls the transport mode selection. When NOT set: Uses stdio transport (traditional MCP mode). When set: Uses http transport (Docker mode) | |
| AIRFLOW_LOG_LEVEL | No | Controls logging verbosity. Values: DEBUG, INFO, WARNING, ERROR | INFO |
| AIRFLOW_API_PASSWORD | Yes | Password for Airflow API authentication | |
| AIRFLOW_API_USERNAME | Yes | Username for Airflow API authentication |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
MCP-Airflow-API inspects and operates one Apache Airflow cluster through its REST API: DAGs, DAG runs, task instances and logs, XComs, pools, variables, connections, configuration, event logs, import errors, plugins, providers, datasets (Airflow 2.x), and assets (Airflow 3.x).
Scope and permissions
Every tool call is a real request to the configured Airflow API, made with the permissions of the configured Airflow account. Use the tools for facts; never guess, simulate, or invent results.
The server targets one API version, set by AIRFLOW_API_VERSION: v1 for Airflow 2.x, v2 for Airflow 3.x. User, role, permission, and dataset tools work only on v1 and return an "available_in: v1 only" error on v2; on v2 use the asset tools instead. Asset tools exist only on v2.
A 401, 403, or 404 response means missing permission, a disabled feature (for example configuration tools when expose_config is off), or a wrong identifier. Report it as-is.
Reporting results
Report what the tool returned. Never claim success after an error, an empty response, or a partial result; quote the error.
Triggering a DAG creates a queued run; it is not a completed run. Say so, and check the run or task state with a read tool when the outcome matters.
Changing state
trigger_dag, pause_dag, unpause_dag, create_connection, update_connection, and delete_connection change the cluster. Run them only when the user asks for that change.
Confirm delete_connection, and any change applied to several DAGs or connections, with the user before running it. For pattern-based targets ("all test DAGs"), list the matches with a read tool first.
Do not repeat passwords, connection secrets, or sensitive variable values in replies unless the user explicitly asks for them.
Identifiers and missing values
Tools need exact identifiers: dag_id (not the display name), dag_run_id, task_id, connection_id, pool name, variable key. Look them up with list tools (list_dags, list_tasks, list_task_instances_all) instead of guessing.
If a required value is missing or ambiguous, ask the user instead of choosing one.
Resolve relative dates ("yesterday", "last week") against the server's current date and pass explicit ISO 8601 timestamps.
Numbers
total_entries is the number of matching items in Airflow; the number of returned items is limited by limit. Do not present one page as the total.
Durations are in seconds. Pool slots are capacity (slots) versus occupied, running, queued, and open slots; they are not CPU or memory usage.
Event and import-error summaries are counts, not rates.
Large results
List tools paginate (default limit is usually 20). Use limit and offset, and follow has_more_pages and next_offset when present. Use fetch_all or large limits only when the user needs every item, because large responses consume many tokens.
Prefer filters (id_contains, state, date ranges, dag_id) over fetching everything.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_dagsB | [Tool Role]: Lists all DAGs registered in the Airflow cluster with pagination support. |
| get_dagC | [Tool Role]: Retrieves detailed information for a specific DAG. |
| get_dags_detailed_batchB | [Tool Role]: Retrieves detailed information for multiple DAGs in batch with latest run information. |
| running_dagsA | [Tool Role]: Lists all currently running DAG runs in the Airflow cluster. |
| failed_dagsB | [Tool Role]: Lists all recently failed DAG runs in the Airflow cluster. |
| trigger_dagC | [Tool Role]: Triggers a new DAG run for a specified Airflow DAG. |
| pause_dagA | [Tool Role]: Pauses the specified Airflow DAG (prevents scheduling new runs). |
| unpause_dagB | [Tool Role]: Unpauses the specified Airflow DAG (allows scheduling new runs). |
| dag_graphB | [Tool Role]: Retrieves task graph structure for the specified DAG. |
| list_tasksB | [Tool Role]: Lists all tasks within the specified DAG. |
| dag_codeC | [Tool Role]: Retrieves the source code for the specified DAG. |
| list_event_logsC | [Tool Role]: Lists event logs from Airflow. |
| get_event_logB | [Tool Role]: Retrieves a specific event log entry. |
| all_dag_event_summaryB | [Tool Role]: Provides summary of event logs across all DAGs. |
| list_import_errorsC | [Tool Role]: Lists import errors in Airflow. |
| get_import_errorB | [Tool Role]: Retrieves a specific import error. |
| all_dag_import_summaryA | [Tool Role]: Provides summary of import errors across all DAGs. |
| dag_run_durationC | [Tool Role]: Analyzes DAG run durations and performance metrics. |
| dag_task_durationC | [Tool Role]: Analyzes task durations within a DAG run. |
| dag_calendarC | [Tool Role]: Shows DAG schedule and execution calendar for a date range. |
| get_healthA | [Tool Role]: Checks Airflow cluster health status. |
| get_versionB | [Tool Role]: Gets Airflow version information. |
| get_configC | [Tool Role]: Retrieves Airflow configuration. |
| list_config_sectionsB | [Tool Role]: Lists all configuration sections with summary. |
| get_config_sectionB | [Tool Role]: Gets all options within a specific configuration section. |
| search_config_optionsC | [Tool Role]: Searches for configuration options matching a term. |
| list_poolsB | [Tool Role]: Lists all pools in Airflow. |
| get_poolB | [Tool Role]: Gets details for a specific pool. |
| list_task_instances_allC | [Tool Role]: Lists task instances with comprehensive filtering options. |
| get_task_instance_detailsC | [Tool Role]: Gets detailed information for a specific task instance. |
| list_task_instances_batchC | [Tool Role]: Lists task instances in batch with date and state filtering. |
| get_task_instance_extra_linksC | [Tool Role]: Gets extra links for a task instance. |
| get_task_instance_logsC | [Tool Role]: Retrieves logs for a specific task instance. |
| list_variablesC | [Tool Role]: Lists all variables in Airflow. |
| get_variableB | [Tool Role]: Gets the value of a specific variable. |
| list_xcom_entriesC | [Tool Role]: Lists XCom entries for a specific task instance. |
| get_xcom_entryC | [Tool Role]: Gets a specific XCom entry. |
| list_connectionsC | [Tool Role]: Lists all connections in Airflow. |
| get_connectionC | [Tool Role]: Gets details for a specific connection. |
| create_connectionC | [Tool Role]: Creates a new connection. |
| update_connectionC | [Tool Role]: Updates an existing connection. |
| delete_connectionC | [Tool Role]: Deletes a connection. |
| list_usersB | [Tool Role]: Lists all users in the Airflow system (v1 API only). |
| get_userC | [Tool Role]: Gets details of a specific user (v1 API only). |
| list_permissionsB | [Tool Role]: Lists all permissions available in the Airflow system (v1 API only). |
| list_rolesB | [Tool Role]: Lists all roles in the Airflow system (v1 API only). |
| list_pluginsA | [Tool Role]: Lists all installed plugins in the Airflow system. |
| list_providersA | [Tool Role]: Lists all provider packages installed in the Airflow system. |
| get_providerB | [Tool Role]: Gets details of a specific provider package. |
| list_datasetsB | [Tool Role]: Lists all datasets in the Airflow system (v1 API only - v2 uses Assets). |
| get_datasetB | [Tool Role]: Gets details of a specific dataset (v1 API only - v2 uses Assets). |
| list_dataset_eventsA | [Tool Role]: Lists dataset events for data lineage tracking (v1 API only - v2 uses Assets). |
| get_dataset_eventsB | [Tool Role]: Gets events for a specific dataset (v1 API only - v2 uses Assets). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 53 tools
Most tools map to a distinct resource+action, but several clusters overlap: list_task_instances_all vs list_task_instances_batch vs get_task_instance_details, list_event_logs/get_event_log/all_dag_event_summary, and list_datasets/get_dataset_events/list_dataset_events (the last two read as near-duplicates). list_dags vs get_dags_detailed_batch vs get_dag is also a subtle distinction an agent could easily misfire on.
The dominant pattern is snake_case verb_noun (list_pools, get_pool, create_connection), which is good. However, a sizeable minority break the verb-first rule: running_dags, failed_dags, dag_graph, dag_code, dag_calendar, all_dag_event_summary, all_dag_import_summary. The mixed conventions are still readable but not predictable.
53 tools is far past the comfortable range for an agent to select from reliably, and Airflow's breadth doesn't fully excuse it. Many families (config, event logs, import errors, dataset events) could be collapsed into fewer parameterized tools, e.g. one list_task_instances with filters instead of two plus a batch variant.
Coverage is lopsided: connections get full CRUD, but variables, pools, users, roles, and datasets are read-only, and there is no way to clear/delete a DAG run, mark a task instance success/failed, or create/delete a DAG. Common operational recovery workflows (clear and rerun, set variable) are dead ends for an agent.