Dagster Mcp

Dagster MCP

An MCP server that gives AI agents full visibility and control over your Dagster instance — like an SRE for your data pipelines.

Works with any MCP client: Claude Code, Claude Desktop, Cursor, and more.

Dagster officially develops and supports their own Dagster Plus MCP server. See the documentation here.

Why this exists

Data pipelines break at 3 AM. Schedules silently stop firing. Assets go stale. Instead of waking up to a dashboard full of red, give your AI agent the tools to monitor, diagnose, and fix your Dagster instance autonomously.

Agent: Checking instance health...
       get_instance_status() -> healthy: false, daemon "SCHEDULER" unhealthy

Agent: Scheduler daemon is down. Let me check recent failures...
       get_runs(statuses=["FAILURE"], limit=5) -> 3 failed runs in the last hour

Agent: Diagnosing the most recent failure...
       get_run_failure_summary("run_abc123") ->
         failed_steps: ["transform_orders"]
         root_cause: "NullPointerError: column 'price' is null"
         suggestions: ["Single step failed — consider re-running from failure"]

Agent: Re-launching the failed job...
       launch_job("etl_pipeline", "my_project") -> run_id: "run_def456", status: STARTED

Agent: One sensor keeps firing on bad data. Checking its ticks...
       get_tick_history("orders_sensor", "SENSOR") -> 12 consecutive FAILURE ticks

Agent: Stopping it until the upstream fix lands...
       stop_sensor("orders_sensor") -> status: STOPPED

What it does

27 tools across 6 categories, designed for autonomous DataOps workflows:

Actions are opt-in: set DAGSTER_READ_ONLY=false to enable write operations.

Quick start

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• A running Dagster instance (self-hosted or Cloud)

Install

The package is published on PyPI.

Option A — run directly with uvx (no install needed):

uvx dagster-mcp

Option B — install with pip:

pip install dagster-mcp

Option C — clone and run:

git clone https://github.com/fabdendev/dagster-mcp.git
cd dagster-mcp
uv sync

Configure

Single environment

Self-hosted:

export DAGSTER_URL=http://localhost:3000

Dagster Cloud:

export DAGSTER_URL=https://myorg.dagster.cloud/prod
export DAGSTER_API_TOKEN=your-dagster-cloud-user-token

Custom auth / proxy headers:

export DAGSTER_EXTRA_HEADERS='{"Authorization":"Bearer your-token","X-My-Header":"value"}'

Multiple environments

Use DAGSTER_ENVS to configure several Dagster instances in one server. Every tool then accepts an optional env parameter so the LLM can target the right instance.

export DAGSTER_ENVS='{
  "prod": {"url": "https://myorg.dagster.cloud/prod", "token": "prod-token"},
  "staging": {"url": "https://myorg.dagster.cloud/staging", "token": "stg-token"},
  "dev": {"url": "http://localhost:3000"}
}'
export DAGSTER_DEFAULT_ENV=prod

When DAGSTER_ENVS is set, DAGSTER_URL / DAGSTER_API_TOKEN / DAGSTER_EXTRA_HEADERS are ignored. If only one env is defined, it is used automatically even without DAGSTER_DEFAULT_ENV.

Add to your MCP client

{
  "mcpServers": {
    "dagster": {
      "command": "uvx",
      "args": ["dagster-mcp"],
      "env": {
        "DAGSTER_URL": "http://localhost:3000"
      }
    }
  }
}

{
  "mcpServers": {
    "dagster": {
      "command": "uvx",
      "args": ["dagster-mcp"],
      "env": {
        "DAGSTER_ENVS": "{\"prod\":{\"url\":\"https://myorg.dagster.cloud/prod\",\"token\":\"prod-token\"},\"dev\":{\"url\":\"http://localhost:3000\"}}",
        "DAGSTER_DEFAULT_ENV": "prod"
      }
    }
  }
}

{
  "mcpServers": {
    "dagster": {
      "command": "uvx",
      "args": ["dagster-mcp"],
      "env": {
        "DAGSTER_URL": "http://localhost:3000"
      }
    }
  }
}

{
  "mcpServers": {
    "dagster": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/dagster-mcp", "dagster-mcp"],
      "env": {
        "DAGSTER_URL": "http://localhost:3000"
      }
    }
  }
}

Tool reference

Runs

Assets

Two-step asset workflow

Start by resolving and reviewing a selection expression:

resolve_asset_selection(
  asset_selection="group:analytics and (kind:dbt or key:*benchmark)"
)

→ {
    "asset_keys": [
      "warehouse/analytics/orders",
      "warehouse/analytics/reranker_benchmark"
    ],
    "assets": [...]
  }

For concrete, unpartitioned assets, pass the returned keys to materialize_assets with any required launch config and tags:

materialize_assets(
  asset_keys=[
    "warehouse/analytics/orders",
    "warehouse/analytics/reranker_benchmark"
  ],
  run_config={"ops": {"benchmark": {"config": {"limit": 1000}}}},
  tags={"triggered_by": "agent"}
)

For partitioned assets, pass the same resolved keys to backfill_assets instead:

backfill_assets(
  asset_keys=["warehouse/analytics/daily_orders"],
  partition_start="2026-07-01",
  partition_end="2026-07-07",
  run_config={"resources": {"warehouse": {"config": {"pool": "benchmark"}}}}
)

resolve_asset_selection is available in both read-only and read-write modes. It returns external, observable, non-executable, and partitioned matches so the caller can inspect the complete result. The write tools re-fetch current asset definitions before execution. resolve_asset_selection and materialize_assets require Dagster 1.9+.

Jobs, Schedules & Sensors

list_jobs filters are independent and use AND semantics when combined. For example, list_jobs(repository_name="example_repository") finds that repository across locations, while list_jobs(repository_name="example_repository", location_name="example_location") targets one repository and code-location pair. Calls with only one filter use a lightweight repository-discovery request followed by one batched job request — it isn't free: that's a second round-trip against Dagster, traded for a smaller payload when only a subset of repositories matches. Request counts per call: 1 for no filters, 1 for both filters, 2 for exactly one filter.

If a code location relevant to the filter failed to load or is still loading, list_jobs raises a RuntimeError naming the location instead of silently returning an empty result — an empty filtered result means no match among code locations Dagster could actually load. A non-empty filtered result can still be incomplete: if some repositories matched, list_jobs returns them rather than raising, even when another code location could not be searched. This check rides along in the same requests above (workspaceOrError, which list_code_locations already queries), so it adds no extra round-trip. The unfiltered call (list_jobs() with no filters) is unchanged: it omits this check and keeps returning whatever is loaded, since an agent won't misread a long inventory listing as "nothing exists" the way it would misread an empty filtered result — use list_code_locations or get_instance_status to check load health directly.

Instance & Code Locations

Write Operations

Schedule/sensor names are unique only within a repository. If the same name exists in several code locations, the start/stop tools refuse to act and list the candidates; pass repository_name / location_name to disambiguate. Successful calls echo the resolved repository and location. | terminate_run | Stop a stuck or runaway run | | reload_code_location | Reload a code location after deploy |

Write tools require DAGSTER_READ_ONLY=false (default is true).

How it differs from Dagster's official AI tooling

Dagster builds and supports its own AI tooling. If you are a Dagster+ customer, start with theirs — it is first-party, needs no local runtime, and reaches Dagster+ platform objects (alerting, Issues, Insights) that this project cannot. This project exists mainly for people running open-source / self-hosted Dagster, which the official server's documented setup does not cover.

Everything in the "official" column comes from Dagster's own docs at https://docs.dagster.io/guides/labs/dagster-mcp (retrieved 2026-07-30), or from Dagster directly in #21. Dagster's docs nowhere state that open-source or self-hosted Dagster is unsupported; what they document is a Dagster-hosted URL, a required Dagster-Cloud-Organization header, and a Dagster+ user token. Their capability matrix is a snapshot of today and Dagster expects to keep adding to it, so treat the gaps below as current rather than permanent.

Use the official Dagster+ MCP server if you are on Dagster+ and want alerting, Issues or Insights/cost analysis from an agent, want no local runtime, or need vendor support and a supplier your procurement process will accept.

Use this project if you run open-source or self-hosted Dagster, or you need asset-level materialization, schedule/sensor control, backfills, or code-location and daemon operations from an agent.

For Dagster+ users the two are complementary rather than competing — nothing stops you running both. This project is not affiliated with or endorsed by Dagster Labs.

Compatibility

The monitoring and existing action tools are tested with Dagster 1.6+. resolve_asset_selection and materialize_assets require Dagster 1.9+ and verify the required GraphQL capabilities before querying or launching. The RunsFilter field name (jobName vs pipelineName) is auto-detected via schema introspection. Configured asset backfills also feature-detect LaunchBackfillParams.runConfigData and return a clear compatibility error when an older schema does not expose it. Schedule and sensor start/stop work on Dagster 1.6+: the stop mutations are sent with the originId/selectorId argument pair sourced from InstigationState.id/selectorId, which modern Dagster re-parses as a compound id and older versions accept directly, so no version branch is needed. The mutations select error messages via the ... on Error interface fragment rather than per-type fragments, because ScheduleNotFoundError only joined ScheduleMutationResult in Dagster 1.9 and spreading it on 1.6-1.8 would fail document validation.

Development

uv sync --extra dev
uv run ruff check dagster_mcp/    # lint
uv run pytest                     # run the test suite
uv run python -m dagster_mcp      # start server locally

License

MIT