mcp-server-airflow-token

A Model Context Protocol (MCP) server for Apache Airflow with Bearer token authentication support, enabling seamless integration with Astronomer Cloud and standalone Airflow instances.

> **Based on mcp-server-apache-airflow by Gyeongmo Nathan Yang**

>

> This fork enhances the original MCP server with Bearer token authentication support, making it compatible with Astronomer Cloud and other token-based Airflow deployments.

Key Enhancements

• ✅ Bearer Token Authentication - Primary authentication method for modern Airflow deployments
• ✅ Astronomer Cloud Compatible - Works seamlessly with Astronomer's managed Airflow
• ✅ Backward Compatible - Still supports username/password authentication
• ✅ Enhanced URL Handling - Correctly handles deployment paths like `/deployment-id`

About

This project implements a Model Context Protocol server that wraps Apache Airflow's REST API, allowing MCP clients to interact with Airflow in a standardized way. It uses the official Apache Airflow client library to ensure compatibility and maintainability.

Feature Implementation Status

Setup

Dependencies

This project depends on the official Apache Airflow client library (`apache-airflow-client`). It will be automatically installed when you install this package.

Environment Variables

Set the following environment variables:

Token Authentication (Recommended)

AIRFLOW_HOST=        # Optional, defaults to http://localhost:8080
AIRFLOW_TOKEN=  # Your Airflow API token
AIRFLOW_API_VERSION=v1                  # Optional, defaults to v1

Basic Authentication (Alternative)

AIRFLOW_HOST=        # Optional, defaults to http://localhost:8080
AIRFLOW_USERNAME=
AIRFLOW_PASSWORD=
AIRFLOW_API_VERSION=v1                  # Optional, defaults to v1

Note: If `AIRFLOW_TOKEN` is provided, it will be used for authentication. Otherwise, the server will fall back to basic authentication using username and password.

Usage with Claude Desktop

First, clone the repository:

git clone https://github.com/nikhil-ganage/mcp-server-airflow-token

Add to your `claude_desktop_config.json`:

With Token Authentication (Recommended)

{
  "mcpServers": {
    "apache-airflow": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "path-to-repo/mcp-server-airflow-token",
        "run",
        "mcp-server-airflow-token"
      ],
      "env": {
        "AIRFLOW_HOST": "https://astro_id.astronomer.run/id",
        "AIRFLOW_TOKEN": "TOKEN"
      }
    }
  }
}

With Basic Authentication

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

For read-only mode (recommended for safety):

Read-only with Token Authentication

{
  "mcpServers": {
    "mcp-server-airflow-token": {
      "command": "uvx",
      "args": ["mcp-server-airflow-token", "--read-only"],
      "env": {
        "AIRFLOW_HOST": "https://your-airflow-host",
        "AIRFLOW_TOKEN": "your-api-token"
      }
    }
  }
}

Read-only with Basic Authentication

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

Replace `path-to-repo` with the actual path where you've cloned the repository.

Astronomer Cloud Configuration Example

For Astronomer Cloud deployments:

{
  "mcpServers": {
    "mcp-server-airflow-token": {
      "command": "uvx",
      "args": ["mcp-server-airflow-token"],
      "env": {
        "AIRFLOW_HOST": "https://your-astronomer-domain.astronomer.run/your-deployment-id",
        "AIRFLOW_TOKEN": "your-astronomer-api-token"
      }
    }
  }
}

Note: The deployment ID is part of your Astronomer Cloud URL path.

Selecting the API groups

You can select the API groups you want to use by setting the `--apis` flag.

uv run mcp-server-airflow-token --apis "dag,dagrun"

The default is to use all APIs.

Allowed values are:

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

Read-Only Mode

You can run the server in read-only mode by using the `--read-only` flag. This will only expose tools that perform read operations (GET requests) and exclude any tools that create, update, or delete resources.

uv run mcp-server-airflow-token --read-only

In read-only mode, the server will only expose tools like:

• Listing DAGs, DAG runs, tasks, variables, connections, etc.
• Getting details of specific resources
• Reading configurations and monitoring information
• Testing connections (non-destructive)

Write operations like creating, updating, deleting DAGs, variables, connections, triggering DAG runs, etc. will not be available in read-only mode.

You can combine read-only mode with API group selection:

uv run mcp-server-airflow-token --read-only --apis "dag,variable"

Manual Execution

You can also run the server manually:

make run

`make run` accepts following options:

Options:

• `--port`: Port to listen on for SSE (default: 8000)
• `--transport`: Transport type (stdio/sse, default: stdio)

Or, you could run the sse server directly, which accepts same parameters:

make run-sse

Installation

You can install the server using pip or uvx:

# Using pip
pip install mcp-server-airflow-token

# Using uvx (recommended)
uvx mcp-server-airflow-token

Development

Setting up Development Environment

1. Clone the repository:

git clone https://github.com/nikhil-ganage/mcp-server-airflow-token.git
cd mcp-server-airflow-token

2. Install development dependencies:

uv sync --dev

3. Create a `.env` file for environment variables (optional for development):

touch .env

> Note: No environment variables are required for running tests. The `AIRFLOW_HOST` defaults to `http://localhost:8080` for development and testing purposes.

Running Tests

The project uses pytest for testing with the following commands available:

# Run all tests
make test

Code Quality

# Run linting
make lint

# Run code formatting
make format

Continuous Integration

The project includes a GitHub Actions workflow (`.github/workflows/test.yml`) that automatically:

• Runs tests on Python 3.10, 3.11, and 3.12
• Executes linting checks using ruff
• Runs on every push and pull request to `main` branch

The CI pipeline ensures code quality and compatibility across supported Python versions before any changes are merged.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

The package is deployed automatically to PyPI when project.version is updated in `pyproject.toml`.

Follow semver for versioning.

Please include version update in the PR in order to apply the changes to core logic.

License

MIT License