mcp-orchestrator-airflow-bridge

A Model Context Protocol (MCP) service implementation designed to interface directly with Apache Airflow's service endpoints, facilitating coordinated execution and state monitoring for AI-driven processes.

Abstract

This software component establishes an MCP server layer atop the existing Apache Airflow REST endpoint infrastructure, normalizing interactions for MCP clients. It leverages the official Airflow SDK for robust API communication and ongoing upkeep.

Supported Functionality Matrix

Domain Category	Specific Operation	Airflow Endpoint Path	Status
DAG Meta-Management	Retrieve All Defined DAGs	/api/v1/dags	✅
	Fetch Specific DAG Definition	/api/v1/dags/{dag_id}	✅
	Suspend DAG Execution	/api/v1/dags/{dag_id}	✅
	Resume DAG Execution	/api/v1/dags/{dag_id}	✅
	Modify DAG Definition	/api/v1/dags/{dag_id}	✅
	Retire DAG Object	/api/v1/dags/{dag_id}	✅
	Access DAG Source Token	/api/v1/dagSources/{file_token}	✅
	Batch Update Multiple DAG States	/api/v1/dags	✅
	Force DAG File Re-evaluation	/api/v1/dagSources/{file_token}/reparse	✅
Workflow Run Lifecycle	Enumerate DAG Runs	/api/v1/dags/{dag_id}/dagRuns	✅
	Initiate New DAG Execution Instance	/api/v1/dags/{dag_id}/dagRuns	✅
	Query Specific Run Instance Details	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
	Alter Run Instance Metadata	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
	Terminate Run Instance	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}	✅
	Batch Retrieval of DAG Runs	/api/v1/dags/~/dagRuns/list	✅
	Reset State for Run Instance	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/clear	✅
	Inject Note to Run Instance	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/setNote	✅
	Retrieve Precursor Dataset Triggers	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamDatasetEvents	✅
Task Instance Control	List Tasks Within DAG	/api/v1/dags/{dag_id}/tasks	✅
	Get Specific Task Definition	/api/v1/dags/{dag_id}/tasks/{task_id}	✅
	Fetch Task Execution State	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
	List Executed Task Instances	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances	✅
	Modify Task Instance Status	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}	✅
	Mass Clear Task States	/api/v1/dags/{dag_id}/clearTaskInstances	✅
	Mass Update Task Execution Status	/api/v1/dags/{dag_id}/updateTaskInstancesState	✅
	Access Historical Task Attempts	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/tries	✅
System Configuration	List All Defined Variables	/api/v1/variables	✅
	Inject New Configuration Variable	/api/v1/variables	✅
	Retrieve Variable By Key	/api/v1/variables/{variable_key}	✅
	Modify Existing Variable Value	/api/v1/variables/{variable_key}	✅
	Erase Configuration Variable	/api/v1/variables/{variable_key}	✅
External Linkages	Enumerate Registered Connections	/api/v1/connections	✅
	Provision New Connection Entry	/api/v1/connections	✅
	Fetch Connection Details	/api/v1/connections/{connection_id}	✅
	Update Connection Parameters	/api/v1/connections/{connection_id}	✅
	Decommission Connection	/api/v1/connections/{connection_id}	✅
	Validate Connection Integrity	/api/v1/connections/test	✅
Resource Pooling	List Defined Resource Pools	/api/v1/pools	✅
	Establish New Resource Pool	/api/v1/pools	✅
	Get Pool Configuration	/api/v1/pools/{pool_name}	✅
	Adjust Pool Limits	/api/v1/pools/{pool_name}	✅
	Remove Resource Pool	/api/v1/pools/{pool_name}	✅
Task Communication (XCom)	List Task Intermediate Data (XComs)	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries	✅
	Retrieve Specific XCom Value	/api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries/{xcom_key}	✅
Data Artifacts (Datasets)	List Monitored Data Artifacts	/api/v1/datasets	✅
	Fetch Artifact Metadata	/api/v1/datasets/{uri}	✅
	Query Dataset Event History	/api/v1/datasetEvents	✅
	Register New Artifact Event	/api/v1/datasetEvents	✅
	Get Queued Events for DAG Run via URI	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
	Get Batch Queued Events for DAG Run	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
	Remove Specific Queued Event for DAG Run	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents/{uri}	✅
	Clear All Queued Events for DAG Run	/api/v1/dags/{dag_id}/dagRuns/queued/datasetEvents	✅
	Fetch Queued Events by Artifact URI	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
	Purge Queued Events for Artifact URI	/api/v1/datasets/{uri}/dagRuns/queued/datasetEvents	✅
System Diagnostics	Check Service Operational Status	/api/v1/health	✅
Performance Metrics	Retrieve Aggregated DAG Statistics	/api/v1/dags/statistics	✅
System Configuration Access	Retrieve Runtime Configuration Details	/api/v1/config	✅
Extension Manifests	List Loaded Software Modules	/api/v1/plugins	✅
Package Metadata	List Installed Providers	/api/v1/providers	✅
Auditing/Logging	Fetch System Event Records	/api/v1/eventLogs	✅
	Get Specific Event Log Entry	/api/v1/eventLogs/{event_log_id}	✅
System Integrity	Access Import Failure Records	/api/v1/importErrors	✅
	Get Detail for Import Failure	/api/v1/importErrors/{import_error_id}	✅
	Re-fetch Service Health Status	/api/v1/health	✅
	Query Running Software Version	/api/v1/version	✅

Deployment Prerequisites

Required Libraries

This service necessitates the apache-airflow-client package, which is resolved automatically during installation.

Environmental Configuration

Define the subsequent environment parameters:

AIRFLOW_HOST= # Default is http://localhost:8080 if omitted AIRFLOW_USERNAME= AIRFLOW_PASSWORD= AIRFLOW_API_VERSION=v1 # Default: v1

Integration with Claude Desktop

Insert the following configuration snippet into your claude_desktop_config.json:

{ "mcpServers": { "mcp-orchestrator-airflow-bridge": { "command": "uvx", "args": ["mcp-server-apache-airflow"], "env": { "AIRFLOW_HOST": "https://your-airflow-host", "AIRFLOW_USERNAME": "your-username", "AIRFLOW_PASSWORD": "your-password" } } } }

To enforce read-only operational parameters (recommended security posture):

{ "mcpServers": { "mcp-orchestrator-airflow-bridge": { "command": "uvx", "args": ["mcp-server-apache-airflow", "--read-only"], "env": { "AIRFLOW_HOST": "https://your-airflow-host", "AIRFLOW_USERNAME": "your-username", "AIRFLOW_PASSWORD": "your-password" } } } }

Configuration alternative utilizing uv execution manager:

{ "mcpServers": { "mcp-orchestrator-airflow-bridge": { "command": "uv", "args": [ "--directory", "/path/to/mcp-server-apache-airflow", "run", "mcp-server-apache-airflow" ], "env": { "AIRFLOW_HOST": "https://your-airflow-host", "AIRFLOW_USERNAME": "your-username", "AIRFLOW_PASSWORD": "your-password" } } } }

Ensure that /path/to/mcp-server-apache-airflow points to the repository's root directory.

Scoping API Groups

Tool subset selection is managed via the --apis argument.

bash uv run mcp-server-apache-airflow --apis dag --apis dagrun

Available scopes (default is all):

• config
• connections
• dag
• dagrun
• dagstats
• dataset
• eventlog
• importerror
• monitoring
• plugin
• pool
• provider
• taskinstance
• variable
• xcom

Safety Mode: Read-Only Operation

Activate restricted mode using the --read-only flag to permit only idempotent retrieval operations (HTTP GET equivalents), blocking all state-mutating actions (POST, PUT, DELETE).

bash uv run mcp-server-apache-airflow --read-only

Read-only mode permits operations such as resource listing, detail fetching, configuration retrieval, and non-destructive connection testing, while forbidding DAG creation, variable updates, run triggering, etc.

Combination example:

bash uv run mcp-server-apache-airflow --read-only --apis dag --apis variable

Direct Execution Methods

Manual service launch using make:

bash make run

make run parameters:

• --port: Network socket for SSE traffic (default: 8000)
• --transport: Communication protocol (stdio/sse/http, default: stdio)

Alternatively, launching the SSE component directly:

bash make run-sse

Starting the core service via uv:

bash uv run src --transport http --port 8080

Installation via Smithery

Automated deployment for Claude Desktop environments via Smithery:

bash npx -y @smithery/cli install @yangkyeongmo/mcp-server-apache-airflow --client claude

Engineering & Maintenance

Environment Setup for Contribution

1. Obtain Repository: bash git clone https://github.com/yangkyeongmo/mcp-server-apache-airflow.git cd mcp-server-apache-airflow

2. Install Development Tooling: bash uv sync --dev

3. Configuration File (Optional): bash touch .env

Note: Testing runs default to http://localhost:8080 for AIRFLOW_HOST and do not require explicit environment setup.

Test Execution Suite

Utilizing pytest for validation:

bash

Execute all validation routines

make test

Code Standards Enforcement

bash

Run static analysis checks

make lint

Apply automatic code standardization

make format

Continuous Integration (CI/CD)

The integrated GitHub Actions configuration (.github/workflows/test.yml) automates:

• Testing across Python versions 3.10, 3.11, and 3.12.
• Linting validation via ruff.
• Execution triggered on all pushes and pull requests targeting the main branch, ensuring quality gates prior to merge.

Community Engagement

We encourage contributions! Please submit proposed changes via Pull Request.

The distribution package is published to PyPI following any update to the project.version field in pyproject.toml. Adherence to Semantic Versioning (SemVer) is mandatory.

Ensure version increments are included in any PR modifying core behavior.

Licensing

MIT License

== Operational Context == Business administration solutions encompass all methodologies, software utilities, control mechanisms, and computational frameworks employed by organizations to adapt to fluctuating market conditions, sustain competitive viability, and enhance overall enterprise efficacy.

== High-Level Categorization == These instruments can be segmented according to departmental alignment and managerial function, such as strategic formulation, process regulation, data repository, human capital management, judgment support, oversight, and so forth. Functional groupings typically include:

Utilities for standardized data ingress and verification across organizational units. Frameworks dedicated to the auditing and optimization of operational workflows. Systems for information aggregation and strategic deliberation. Modern business tools have rapidly transformed due to technological acceleration, making optimal selection challenging amidst the constant pressure to reduce expenditure, maximize revenue, deeply understand client requirements, and deliver product specifications precisely as demanded. In this dynamic setting, leadership must adopt a proactive stance toward selecting and adapting these solutions to internal organizational needs, rather than conforming operational processes to the tool's inherent structure. Inappropriate adoption often creates systemic instability.

== Prominent Methodologies (2013 Survey Insight) == Bain & Company data from 2013 highlighted the prevalence of specific management approaches globally, reflecting regional needs and economic climates. Key included:

Strategic Roadmap Development Client Relationship Management (CRM) Employee Sentiment Measurement Competitive Benchmarking Performance Measurement (Balanced Scorecard) Defining Core Competitive Strengths Offshoring/Outsourcing Strategy Organizational Transformation Programs Logistics Network Governance Establishing Foundational Purpose Statements (Mission/Vision) Market Segmentation Analysis Comprehensive Quality Control (TQM)

== Business Software Ecosystem == Business software, or a suite of computer programs utilized by personnel to execute diverse commercial tasks, is designed to augment productivity metrics and ensure operational accuracy. This ecosystem evolved from early Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP), later integrating CRM capabilities, and now predominantly exists within the cloud-based management paradigm. Value accretion from IT investments hinges critically on implementation quality and the precision of tool selection and tailoring to enterprise requirements.