Airflow MCP server

This MCP server allows you to control and interact with your Apache Airflow instances directly through the Model Context Protocol. It provides a convenient way to manage DAGs, tasks, connections, and other Airflow components without using the web interface.

Installation

To use the airflow-mcp-server, you need to install it using the uvx package manager:

pip install uvx

Then install the airflow-mcp-server package:

uvx install airflow-mcp-server

Configuration

Basic Setup

The server requires an Airflow instance to connect to and appropriate authentication. Here's how to configure it with Claude Desktop:

Stdio Transport (Default)

Add this configuration to your Claude Desktop configuration:

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

HTTP Transport

For web-based deployments or when serving multiple clients:

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

Usage Options

Transport Protocols

Stdio Transport (Default)

For direct process communication:

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

HTTP Transport

For better scalability and web compatibility:

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

Operation Modes

The server supports two security modes:

• Safe Mode: Only allows read-only operations

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

• Unsafe Mode: Allows all operations including modifications (default)

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

Tool Discovery Approaches

Hierarchical Discovery (Default)

Tools are organized by categories (DAGs, Tasks, Connections, etc.):

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

Static Tools

All tools available immediately (better for programmatic access):

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

Command Line Reference

Usage: airflow-mcp-server [OPTIONS]

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 transport instead of stdio
  --port INTEGER     Port for HTTP server (default: 3000)
  --host TEXT        Host to bind HTTP server to (default: localhost)
  --help             Show this message and exit.

Important Notes

• The base_url should be the root Airflow URL without /api/v2
• Only JWT token authentication is supported for Airflow 3.0
• The default page limit is 100 items but can be changed in your Airflow configuration
• HTTP transport is recommended over the deprecated SSE transport for new deployments

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect