Airflow MCP Server

airflow-mcp-server: An MCP Server for controlling Airflow 3

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

MCPHub Certification

This MCP server is certified by MCPHub. This certification ensures that airflow-mcp-server follows best practices for Model Context Protocol implementation.

Find on Glama

Overview

A Model Context Protocol server for controlling Airflow via Airflow APIs.

Demo Video

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

Setup

Usage with Claude Desktop

Stdio Transport (Default)

{

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

See CONFIG.md for IDE-specific configuration examples across popular MCP clients.

HTTP Transport

{

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

Note:

- Set base_url to the root Airflow URL (e.g., http://localhost:8080).

- Do not include /api/v2 in the base URL. The server will automatically fetch the OpenAPI spec from ${base_url}/openapi.json.

- Only JWT token is required for authentication. Cookie and basic auth are no longer supported in Airflow 3.0.

Transport Options

The server supports multiple transport protocols:

Stdio Transport (Default)

Standard input/output transport for direct process communication:

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

HTTP Transport

Uses Streamable HTTP for better scalability and web compatibility:

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

Note: SSE transport is deprecated. Use --http for new deployments as it provides better bidirectional communication and is the recommended approach by FastMCP.

Operation Modes

The server supports two operation modes:

• Safe Mode (--safe): Only allows read-only operations (GET requests). This is useful when you want to prevent any modifications to your Airflow instance.
• Unsafe Mode (--unsafe): Allows all operations including modifications. This is the default mode.

To start in safe mode:

airflow-mcp-server --safe

To explicitly start in unsafe mode (though this is default):

airflow-mcp-server --unsafe

Tool Discovery Modes

The server supports two tool discovery approaches:

• Hierarchical Discovery (default): Tools are organized by categories (DAGs, Tasks, Connections, etc.). Browse categories first, then select specific tools. More manageable for large APIs.
• Static Tools (--static-tools): All tools available immediately. Better for programmatic access but can be overwhelming.

To use static tools:

airflow-mcp-server --static-tools

Command Line Options

Usage: airflow-mcp-server [OPTIONS]

MCP server for Airflow

Options: -v, --verbose Increase verbosity -s, --safe Use only read-only tools -u, --unsafe Use all tools (default) --static-tools Use static tools instead of hierarchical discovery --base-url TEXT Airflow API base URL --auth-token TEXT Authentication token (JWT) --http Use HTTP (Streamable HTTP) transport instead of stdio --sse Use Server-Sent Events transport (deprecated, use --http instead) --port INTEGER Port to run HTTP/SSE server on (default: 3000) --host TEXT Host to bind HTTP/SSE server to (default: localhost) --help Show this message and exit.

Using Resources

Point the server at a folder of Markdown guides whenever you want agents to reference local documentation:

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

• Every top-level .md/.markdown file becomes a read-only resource (file:/// ) visible in your MCP client.
• The first # Heading in each file (if present) is used as the resource title; otherwise the filename stem is used.
• Set AIRFLOW_MCP_RESOURCES_DIR=/path/to/docs if you prefer environment-based configuration.
• Update the files on disk and restart the server to refresh the resources list.

Considerations

Authentication

• Only JWT authentication is supported in Airflow 3.0. You must provide a valid AUTH_TOKEN.

Page Limit

The default is 100 items, but you can change it using maximum_page_limit option in [api] section in the airflow.cfg file.

Transport Selection

• Use stdio transport for direct process communication (default)
• Use HTTP transport for web deployments, multiple clients, or when you need better scalability
• Avoid SSE transport as it's deprecated in favor of HTTP transport