airflow-mcp-gateway: An MCP Endpoint for Airflow Orchestration Control

mcp-name: io.github.abhishekbhakat/airflow-mcp-server

MCPHub Validation Seal

This gateway instance has successfully achieved certification from MCPHub. This credential confirms adherence to established best practices for Model Context Protocol deployment.

Discover on Glama

Synopsis

A Model Context Protocol server designed to govern and inspect Airflow operations utilizing Airflow's official Application Programming Interfaces.

Demonstration Video

https://github.com/user-attachments/assets/f3e60fff-8680-4dd9-b08e-fa7db655a705

Integration Guide

Usage within Claude Desktop

Standard I/O Conduit (Default Method)

{
    "mcpServers": {
        "airflow-mcp-gateway": {
            "command": "uvx",
            "args": [
                "airflow-mcp-server",
                "--base-url",
                "http://localhost:8080",
                "--auth-token",
                "<jwt_token>"
            ]
        }
    }
}

Airflow Version 3 Plugin (HTTP Streaming on /mcp)

Install the accompanying plugin package alongside the core server to expose a native MCP endpoint directly within the Airflow web application server:

pip install "airflow-mcp-server[airflow-plugin]"

• The plugin is automatically recognized and loaded via Airflow's entry point mechanism.
• Accessible Endpoint: http(s)://<airflow-host>/mcp
• Protocol: Stateless; every interaction necessitates an Authorization: Bearer <access-token> header.
• Operation Modes (Configurable per Request): Secure by default, or append ?mode=unsafe to permit write/mutation actions.

Network Transport Configuration

{
    "mcpServers": {
        "airflow-mcp-gateway-net": {
            "command": "uvx",
            "args": [
                "airflow-mcp-server",
                "--http",
                "--port",
                "3000",
                "--base-url",
                "http://localhost:8080",
                "--auth-token",
                "<jwt_token>"
            ]
        }
    }
}

Crucial Detail: - Ensure base_url points exclusively to the Airflow root address (e.g., http://localhost:8080). - Avoid suffixing with /api/v2. The gateway dynamically retrieves the required OpenAPI specification from ${base_url}/openapi.json. - Only JSON Web Tokens (JWT) are accepted for authorization; legacy cookie or basic authentication mechanisms are unsupported since Airflow 3.0.

Conduit Selection Strategies

The gateway facilitates connectivity across several communication protocols:

Standard I/O Conduit (Default)

Utilizes standard process input and output streams for direct inter-process communication:

airflow-mcp-server --safe --base-url http://localhost:8080 --auth-token <jwt>

Network Transport (HTTP)

Employs Streamable HTTP for enhanced performance in web-based setups and improved client compatibility:

airflow-mcp-server --safe --http --port 3000 --base-url http://localhost:8080 --auth-token <jwt>

Note: The Server-Sent Events (SSE) transport is now obsolete. For contemporary deployments, migrate to the --http flag, as it offers superior bidirectional communication capabilities and is the recommended methodology by the FastMCP framework.

Operational Contexts

The server supports distinct operational modes governing interaction permissions:

• Secure Mode (--safe): Restricts operations solely to retrieval actions (HTTP GET requests). Ideal when modifications to the Airflow instance must be strictly prohibited.
• Insecure Mode (--unsafe): Permits all actions, including data modifications (default setting).

To initialize in secure mode:

airflow-mcp-server --safe

To explicitly invoke insecure mode (though this is the default behavior):

airflow-mcp-server --unsafe

Tool Enumeration Patterns

The server supports two primary methods for exposing its available operations:

• Hierarchical Indexing (Standard): Tools are logically grouped by domain (e.g., DAG Definitions, Task Instances, Configuration Settings). Users navigate through categories before selecting granular tools. Best suited for complex APIs.
• Flat Listing (--static-tools): All discoverable tools are presented immediately upon connection. Better for automated scripting but can present a high volume of options.

To activate the static tool exposition method:

airflow-mcp-server --static-tools

Executable Parameters

Usage: airflow-mcp-server [OPTIONS]

  MCP gateway for Airflow administration

Options:
  -v, --verbose      Augment output logging detail
  -s, --safe         Engage read-only toolset exclusively
  -u, --unsafe       Activate all available tools (default setting)
  --static-tools     Use static listing mode instead of structural hierarchy
  --base-url TEXT    The root Uniform Resource Locator for the Airflow API
  --auth-token TEXT  The required authentication credential (JWT format)
  --http             Activate HTTP (Streamable HTTP) conduit over stdio
  --sse              Activate Server-Sent Events conduit (deprecated; use --http)
  --port INTEGER     Network port for HTTP/SSE server binding (default: 3000)
  --host TEXT        Network address for HTTP/SSE server binding (default: localhost)
  --help             Display this assistance message and terminate.

Critical Points of Attention

Authorization Protocol

• Airflow versions 3.0 and later mandate JWT-based authentication. A valid AUTH_TOKEN must be supplied.

Pagination Threshold

The system defaults to retrieving 100 records per batch. This limit can be altered by setting the maximum_page_limit parameter within the [api] configuration section of the airflow.cfg file.

Conduit Selection Rationale

• Choose stdio for direct, local execution contexts.
• Choose HTTP for distributed web clients, multi-client environments, or when optimizing for throughput.
• Discontinue use of SSE transport; migration to the enhanced HTTP transport mechanism is strongly advised.

Progress Log

• [x] Compatibility verification for Airflow 3.x
• [x] Automated OpenAPI Specification parsing implementation
• [x] Implementation of Safe/Unsafe operational control flags
• [x] Refined tool description generation via list_tools endpoint.
• [x] Logic implemented to extract system configuration values (specifically page limits)
• [x] Support established for both HTTP and deprecated SSE communication channels
• [ ] Review required for reliance on environment variables (considering Airflow plugin constraints, native configuration may be preferable)

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," often simply termed "the cloud".

== Essential Attributes == In 2011, the United States' National Institute of Standards and Technology (NIST) delineated five core characteristics defining cloud systems. The official NIST stipulations are:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== Historical Context ==

The genesis of distributed computing, an antecedent to cloud infrastructure, traces back to the 1960s with the rise of time-sharing concepts popularized through remote job entry (RJE). The prevalent operational model involved users submitting batch jobs to dedicated operations staff who executed them on mainframe systems. This era was characterized by pioneering efforts to democratize access to significant computational power via time-sharing, focusing on maximizing utilization of infrastructure, platform layers, and application efficiency for a broader user base. The adoption of the 'cloud' visual metaphor for abstracted services originated in 1994, utilized by General Magic to depict the comprehensive domain of locations that mobile software agents within their Telescript framework could traverse. This attribution is credited to David Hoffman, a communications specialist at General Magic, acknowledging its established use in telecommunications and network diagrams. The term 'cloud computing' gained broader public recognition in 1996 when Compaq Computer Corporation formalized a strategic business blueprint concerning the future of computation and the Internet. The company's initial objective was to superch