airflow

airflow-mcp-server provides a programmable interface to control Airflow via its REST/OpenAPI endpoints. It exposes tools organized by categories (DAGs, Tasks, Connections, and more) that you can discover and invoke through MCP clients. By using the Stdio transport, you run the server as a process and connect locally; the HTTP transport option is available for remote or scalable deployments. Authentication is performed with a JWT token, and you can choose between read-only (safe) or full-capability (unsafe) modes depending on your operational needs. The server can also serve a static-tools mode if you want all tools to be exposed upfront, or a hierarchical discovery mode for a more navigable tool set. You can point agents to a local Markdown resource directory to have agents reference documentation locally, which aids in offline or guided use cases. The server automatically pulls the OpenAPI spec from the base URL you provide, so ensure your Airflow instance is reachable at that URL.

Typical usage patterns include starting the server in stdio mode for development and debugging, or enabling the HTTP transport for production or multi-client access. When using HTTP transport, you’ll benefit from streaming bidirectional communication and better scalability. Remember to provide the base URL of your Airflow instance (without /api/v2), and the JWT token for authentication. The server supports options to limit operations to safe mode for read-only tasks, or to run in unsafe mode for full control, as well as tooling for static discovery if you prefer immediate tool exposure.

Prerequisites:

• A machine with Python 3.8+ installed
• Access to install Python packages (pip or pipx)
• Network access to install uvx and to reach your Airflow instance at the base URL you choose

Installation steps:

1. Verify Python is installed

   • On macOS/Linux: python3 --version
   • On Windows: py --version

2. Install uvx (the MCP client CLI used by this server)

   • Option A (recommended): install via pipx
     • python3 -m pip install --user pipx
     • python3 -m pipx ensurepath
     • pipx install uvx
   • Option B: install via pip (if you don’t use pipx)
     • python3 -m pip install uvx

3. Verify installation

   • uvx --version

4. Prepare configuration for your MCP client

   • Create a configuration file (e.g., mcp_config.json) with the content provided in the mcp_config section below. Save it locally or embed it in your MCP client workflow.

5. Run the MCP server configuration (example using the provided mcp_config)

   • Ensure your Airflow instance is up and reachable at http://localhost:8080
   • Use your MCP client to load the configuration:
     • For environments using JSON config, load the mcp_config.json content into your MCP client tooling.

Notes:

• If you plan to expose the server publicly, consider running the server behind a reverse proxy and using secure transport (HTTPS) and proper authentication handling for the JWT token.

Tips and common considerations:

• Base URL: Use the root Airflow URL (e.g., http://localhost:8080). Do not include /api/v2 in the base URL; the server will fetch the OpenAPI spec from /openapi.json automatically.
• Authentication: Only JWT tokens are supported for Airflow 3.0 as per this MCP server; cookies or basic auth are not supported.
• Transport choices: Prefer HTTP transport for scalable deployments. SSE is deprecated; avoid using it in new setups.
• Safe vs Unsafe mode: Use safe mode to expose only read-only tools for auditing or monitoring; switch to unsafe for full operational control.
• Resources: You can point the server at a local directory with Markdown guides to expose file-based resources to MCP clients. The first heading in each Markdown file becomes the resource title.
• Environment variables: You can set AIRFLOW_MCP_RESOURCES_DIR to point to your local docs directory; otherwise configure via your command-line options or MCP client configuration.