dolphin-mcp-pilot
Provides tools for operating Apache DolphinScheduler, including managing projects, creating and cloning workflows and DAGs, configuring cron schedules, controlling process and task instances, viewing logs, managing resources, rolling back workflow versions, monitoring, and accessing raw DolphinScheduler APIs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dolphin-mcp-pilot Find the latest failed workflow and show the failed task log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dolphin-mcp-pilot
A production-ready MCP server for Apache DolphinScheduler (小海豚).
dolphin-mcp-pilot exposes 53+ tools for projects, workflows, DAG creation, schedules, instances, resources, logs, monitoring and raw API passthrough — designed for AI agents that need to operate DolphinScheduler beyond basic read-only usage.
🎯 Why this project?
Most public DolphinScheduler MCP servers only cover basic read/list/start/stop scenarios. This project is designed for real operations work:
✅ Create SQL / DAG workflows in one line
✅ Manage schedules (create / online / offline / delete)
✅ Control process instances (pause / resume / rerun / rerun-from-failure)
✅ View task logs, force task success / skip failed task
✅ Manage resources (view/update content)
✅ Roll back workflow versions, clone workflows
✅ Use raw API as a safety valve
✅ Support multi-tenant per-request auth
Related MCP server: Apache Airflow MCP Server
🚀 Key features
53+ tools covering most practical DS operations
Two auth modes: API Token (
X-DS-Token) or User/Password (X-DS-User+X-DS-Password)Multi-tenant HTTP mode: each caller can use its own credentials
MCP 2.0 stateless HTTP with automatic compatibility for MCP 1.x clients
Workflow creation: simple SQL and complex DAG workflows with multiple task types
Schedule management (cron-based)
Instance lifecycle control (pause/resume/rerun/rerun-from-failure/delete)
Resource content management and version rollback / workflow clone
Raw API passthrough for uncovered edge cases
🚀 Quick Start
Prerequisites
A running DolphinScheduler 3.x instance whose API is reachable from Docker
Docker with Compose v2 (
docker compose version)A DolphinScheduler API token (recommended), or a username and password
# 1. Clone the repository
git clone https://github.com/iflytek/dolphin-mcp-pilot.git
cd dolphin-mcp-pilot
# 2. Configure environment
cp .env.example .env
# Edit .env — set DS_URL and DS_TOKEN (or DS_USER/DS_PASSWORD)
# Example DS_URL: http://your-dolphinscheduler-host:12345/dolphinscheduler
# 3. Build and start the service from this checkout
docker compose --profile dev up -d dolphin-mcp-pilot-dev
# 4. Confirm that the container is healthy
docker compose --profile dev psThe MCP endpoint is now http://localhost:8001/mcp/ (the trailing slash is required).
Add it to an HTTP/SSE-capable MCP client:
{
"mcpServers": {
"dolphinscheduler": {
"type": "sse",
"url": "http://localhost:8001/mcp/",
"headers": { "X-DS-Token": "your_api_token" }
}
}
}As a safe first check, ask your agent: “List my DolphinScheduler projects and workflows. Do not make any changes.” For client-specific configuration and username/password auth, see Client Config.
💡 Common use cases
Scenario | Example request | Main tools |
Investigate a failed run | “Find the latest failed workflow, show the failed task and its log, and suggest the next action without changing anything.” |
|
Backfill missing data | “Backfill 2026-08-01 through 2026-08-07 serially, starting from the validation task and including downstream tasks.” |
|
Create and schedule a workflow | “Create a daily SQL workflow, add its cron schedule, and show me the definition before putting it online.” |
|
Give multiple agents controlled access | Run one HTTP MCP service while each caller supplies its own DolphinScheduler credentials. | Per-request |
The tools can also pause, resume, rerun, clone, and roll back workflows; manage resources; and
fall back to raw DolphinScheduler APIs for uncovered operations. Start with ds_help(category="quickstart")
inside your MCP client to discover the recommended workflow for each task.
📚 Documentation
Document | Description |
Docker Compose (dev/prod), from source, as package, run modes | |
Environment variables, auth options, Compose tunables | |
Production deployment, Compose reference, verify, troubleshoot | |
Feature comparison table, tool categories | |
MCP client setup (CodeBuddy, Claude Desktop, etc.), multi-tenant auth | |
All 53+ tools, parameter conventions, error handling (中文) | |
Common issues and solutions (中文) |
✨ What's new
MCP 2.0: supports the stateless 2026-07-28 protocol while keeping legacy handshake clients and stdio configurations working.
Guided troubleshooting:
ds_list_process_instancesattaches anext_actionhint to RUNNING/FAILURE instances, pointing agents tods_list_task_instancesto inspect individual task nodes.Reliable backfill ordering: serial complement uses the
complementStartDate/complementEndDaterange format so DolphinScheduler generates instances in strict day-by-day order.Flexible task params:
ds_update_task_paramaccepts bothsnake_caseandcamelCasefield names and reports ignored fields.
🤝 Contributing
Contributions are welcome. See CONTRIBUTING.md for project changes, or follow the example contribution guide to share a tested MCP client configuration.
Used dolphin-mcp-pilot for something real? Write it up in cases/ — a gallery of
community usage stories (agent-driven DolphinScheduler ops), each linked to a public post.
📄 License
🙏 Acknowledgments
Built with the official MCP Python SDK and inspired by the Apache DolphinScheduler community.
Available Tools
60 toolsds_clone_workflowA
Clone/copy a workflow.
Args: project_name: Project name source_workflow_code: Source workflow code new_name: New workflow name description: New workflow description (empty = copy source description) auto_online: Auto-release after cloning
Returns: { 'success': True, 'workflow_code': int, # New workflow code 'source_code': int, 'name': str, ... }
Inputs: new_name (required), project_name (required), source_workflow_code (required), auto_online, +1 more.
ds_complement_dataA
Backfill (complement) workflow data for date range or single partition.
Recommended usage (v2.0.14):
Single partition: partition_date="2024-01-01" (clearer semantics, recommended)
Date range: start_date + end_date (multi-partition backfill)
From specific task: start_task_names + task_depend_type="TASK_POST"
Single task only: start_task_names + task_depend_type="TASK_ONLY"
⚠️ Important (v2.0.19):
Default mode: RUN_MODE_SERIAL (one partition at a time, safer)
Parallel mode: run_mode="RUN_MODE_PARALLEL" (multiple partitions concurrently, higher risk)
Before backfill: check dependency chain with ds_get_workflow → analyze upstream deps
Minimize scope: prefer start_task_names + TASK_POST to backfill from target task forward
Mandatory standard: don't backfill entire workflow unless full-chain rerun is explicitly needed
Args: project_name: Project name workflow_code: Process-definition code start_date: Start date yyyy-MM-dd (for range backfill) end_date: End date yyyy-MM-dd (for range backfill) partition_date: Single partition yyyy-MM-dd (alternative to start_date+end_date, recommended for clarity) start_task_names: Optional list of task names to start from (backfills these + their downstream tasks) task_depend_type: Dependency type (default TASK_POST: from start tasks forward; TASK_ONLY: start tasks only; TASK_PRE: start tasks + upstream) run_mode: RUN_MODE_SERIAL (default, one at a time) or RUN_MODE_PARALLEL (concurrent)
Serial ordering guarantee (v2.0.18): In RUN_MODE_SERIAL, the request is submitted using DS's continuous range fields complementStartDate / complementEndDate, so DS generates instances strictly in ascending day order. Discrete date-list formats (complementScheduleDateList / comma-separated) do not guarantee ordering and are only used as fallbacks. The chosen format is reported in the return value's "format" field ("date_range" / "comma_separated" / "json_list").
Examples: # Single partition (recommended) ds_complement_data(workflow_code=123, partition_date="2024-01-01")
# Date range (serial mode, safer)
ds_complement_data(workflow_code=123, start_date="2024-01-01", end_date="2024-01-31")
# From specific task forward (minimize scope)
ds_complement_data(workflow_code=123, partition_date="2024-01-01",
start_task_names=["ads_table"], task_depend_type="TASK_POST")
# Parallel mode (higher concurrency, more resource usage)
ds_complement_data(workflow_code=123, start_date="2024-01-01", end_date="2024-01-10",
run_mode="RUN_MODE_PARALLEL")
Inputs: project_name (required), workflow_code (required), end_date, run_mode, +4 more.
ds_create_dag_workflowA
Create a generic DAG workflow supporting any task type (SQL/SHELL/PYTHON/DEPENDENT/SUB_PROCESS/HTTP etc.).
Args:
project_name: Project name
name: Workflow name
tasks: Task definition list (see examples below)
relations: Dependency list [{"from": "taskA", "to": "taskB"}]; empty "from" = start node
description: Description
schedule: Whether to create a schedule
schedule_cron: Cron expression (7-field Quartz style)
locations: Optional node coordinates [{"task_name": "check", "x": 100, "y": 100}]
Leave empty for auto-layout (horizontal, 300x200 spacing)
tasks example:
[
# SHELL task (script required, resource_list optional)
{"name": "check", "type": "SHELL",
"script": "#!/bin/bash
python3 /public/check_partition.py table_name $[yyyyMMdd-1]", "resource_list": [67], # optional: referenced resource id or path "fail_retry_times": 3}, # optional: retry count on failure
# SQL task (datasource_id + sql required)
{"name": "sql1", "type": "SQL",
"datasource_id": 1, "sql": "SELECT 1",
"sql_type": "HIVE", # optional, default HIVE
"sql_type_select": 1}, # optional, 0=query 1=non-query (default 1)
# DEPENDENT task (wait for upstream workflow completion)
{"name": "wait", "type": "DEPENDENT",
"depend_items": [{"project_code": 123, "definition_code": 456,
"cycle": "day", "date_value": "today"}]},
# SUB_PROCESS task (invoke a sub-workflow)
{"name": "sub", "type": "SUB_PROCESS",
"sub_process_code": 21505676237440},
# HTTP task
{"name": "notify", "type": "HTTP",
"http_url": "https://api.example.com/callback",
"http_method": "POST"}
]
relations example:
[
{"from": "", "to": "check"}, # check is a start node (empty "from")
{"from": "check", "to": "sql1"},
{"from": "wait", "to": "sql1"} # wait and check run in parallel, both feed sql1
]
resource_list format:
- Recommended: resource_id (int): [67, 58]
- Or full path (str): ["/public/check_partition.py"]
- Paths must start with /
- Use ds_list_resources() to view all resources with their ids and paths
Inputs: name (required), tasks (required), relations (required), project_name (required), +4 more.
ds_create_folderA
Create a folder in the resource area.
Args: name: Folder name (no path prefix, e.g. "scripts") current_dir: Parent directory path, default root "/" resource_type: FILE or UDF
Inputs: name (required), current_dir, resource_type.
ds_create_projectA
Create a new project owned by the current user.
Fails if a project with the same name already exists; check with ds_list_projects first. Use ds_rename_project to change it later.
Args: name: Project name, unique in DolphinScheduler description: Optional description
Returns: {"id": int, "code": int, "name": str}; other tools take the project by name.
Inputs: name (required), description.
ds_create_workflowB
Create a workflow (supports simple SQL mode and complex DAG mode).
Mode 1 - Simple SQL (backward compatible):
Provide sql_statements + datasource_id
Multiple SQL separated by ";;;" are executed serially
Mode 2 - Complex DAG:
Provide tasks_json + relations_json
tasks_json: JSON array string, each task contains name, taskType, taskParams etc.
relations_json: JSON array string defining task dependencies (preTaskName -> postTaskName)
Args: project_name: Project name name: Workflow name description: Description sql_statements: [Mode 1] SQL, multiple separated by ";;;" datasource_id: [Mode 1] Datasource ID sql_ds_type: [Mode 1] SQL type (HIVE/MYSQL) tasks_json: [Mode 2] Task definition JSON array string relations_json: [Mode 2] Task relation JSON array string schedule: Whether to create a schedule schedule_cron: Quartz 7-field cron expression schedule_start: Schedule start time (defaults to today) schedule_end: Schedule end time (defaults to 2030-12-31) auto_online: Whether to auto-release workflow and schedule
Inputs: name (required), project_name (required), schedule, tasks_json, +9 more.
ds_delete_process_instanceA
Permanently delete a finished workflow instance and its task records.
Irreversible. DolphinScheduler rejects deleting a RUNNING instance; stop it first with ds_stop_process_instance. Does not affect the workflow definition.
Args: project_name: Project name process_instance_id: Instance ID (from ds_list_process_instances)
Returns: {"process_instance_id": int, "status": "deleted"}
Inputs: project_name (required), process_instance_id (required).
ds_delete_projectA
Delete an entire project, cascading to all workflows, schedules and instances. This is irreversible - use with caution.
Inputs: project_name (required).
ds_delete_resourceA
Delete a resource (file or folder).
⚠️ Warning: Deletion is irreversible. Resources referenced by workflow tasks will cause those tasks to fail on next execution.
DS behavior: Deleting a non-empty folder returns error 20018. Use recursive=True to delete children first, then the folder.
Args: resource_id: Resource ID recursive: Delete children recursively (for folders, default False)
Returns: {"resource_id", "status", "deleted_children"}
Inputs: resource_id (required), recursive.
ds_delete_scheduleA
Delete a schedule (takes it offline first).
Inputs: schedule_id (required), project_name (required).
ds_delete_workflowA
Delete workflow(s) by code (takes offline first). Supports single or batch delete.
v2.0.12: merged ds_batch_delete_workflows.
workflow_code=12345: delete single workflow
workflow_code=[12345, 67890]: batch delete (each independent; one failure doesn't block others)
Args: project_name: Project name workflow_code: Process-definition code (int for single, list for batch)
Returns: Single: {"workflow_code": int, "status": "deleted"} Batch: {"total": int, "deleted": int, "failed": int, "deleted_codes": [...], "failed_details": [...]}
Inputs: project_name (required), workflow_code (required).
ds_download_resourceA
Download a resource file (supports binary, e.g. jar, zip).
Args: resource_id: Resource ID save_to: Optional local save path (accessible to MCP server process). If empty, returns base64-encoded content.
Returns: If save_to provided: {"resource_id", "saved_to", "size"} Otherwise: {"resource_id", "size", "content_base64"}
Inputs: resource_id (required), save_to.
ds_force_task_successA
Force mark a task as success (dangerous — bypasses actual execution).
⚠️ Warning: Use only when task is stuck/failed but you've verified data correctness. This does NOT rerun the task — it only changes the state flag.
Inputs: project_name (required), task_instance_id (required).
ds_get_latest_failure_logA
One-click fetch of all failed task logs from the latest failed instance.
Combines 3 common troubleshooting steps (list instances → list tasks → fetch logs).
v2.0.10: Added per-step error handling — returns partial diagnostic info even if some steps fail.
Args: project_name: Project name workflow_code: Process-definition code log_limit: Lines of log to fetch per failed task (default 500)
Returns: { "workflow_code": int, "instance_id": int, # Latest failed instance ID "instance_state": "FAILURE", "start_time": str, "failed_tasks": [ # All failed tasks { "task_instance_id": int, "task_name": str, "task_type": str, "start_time": str, "end_time": str, "log_tail": str # Last log_limit lines } ], "errors": [...] # v2.0.10: Per-step error messages "hint": ... }
Inputs: project_name (required), workflow_code (required), log_limit.
ds_get_resource_by_nameA
Find a resource (file or folder) by full path, returning id and metadata.
Implementation: uses /resources/list recursive search (avoids /resources/query-by-name due to known DS bug).
Args: full_name: Full resource path, e.g. "public/test.py" or "scripts" resource_type: Resource type, default FILE
Inputs: full_name (required), resource_type.
ds_get_schedule_alert_configC
Read safe original alert/execution fields; never writes or runs a workflow.
Inputs: schedule_id (required), project_name (required).
ds_get_task_detailA
Read full parameters of a single task (returns only that task, not the whole DAG).
Added in v2.0.12 for the "verify a task change took effect" scenario, avoiding pulling a huge DAG payload.
Args: project_name: Project name workflow_code: Process-definition code task_name: Task name (exact match)
Returns: { "task_code": int, "task_name": str, "task_type": str, "task_params": {...}, # Full taskParams (preStatements/postStatements/sql/script etc.) "description": str, "fail_retry_times": int, "timeout": int, ... }
Inputs: task_name (required), project_name (required), workflow_code (required).
ds_get_task_logA
Fetch task execution log (supports pagination).
Args: task_instance_id: Task instance ID (from ds_list_task_instances) skip_line_num: Skip first N lines (for pagination) limit: Max lines to fetch (default 1000)
Returns: { "task_instance_id": int, "log": str, "line_start": int, "line_count": int, "hint": str }
Inputs: task_instance_id (required), limit, skip_line_num.
ds_get_workflowA
Read a single workflow definition (DAG, global params, node coordinates, etc.).
Args: project_name: Project name workflow_code: Process-definition code (from ds_list_workflows) compact: Compact mode (default False). When True, returns only metadata and task summary without full taskParams/SQL, greatly reducing token usage. Suitable when you only need to understand DAG structure.
Inputs: project_name (required), workflow_code (required), compact.
ds_helpA
Interactive guide to DolphinScheduler MCP tools.
Call without arguments to see all categories, or pass a category name to view tools and workflows for that category.
Available categories:
quickstart: New user onboarding guide with common scenarios
project: Project CRUD (list/create/rename/delete)
workflow: Basic workflow operations (create/list/get/update/delete/release/run)
workflow_advanced: DAG editing, task updates, version management, cloning
instance: Process instance management, log retrieval, failure troubleshooting
schedule: Schedule configuration (cron/online/offline/delete)
resource: File and folder management (upload/download/view/update/delete)
monitor: Cluster health monitoring (master/worker status)
user: User and tenant queries
raw: Raw API passthrough for advanced use
Args: category: Category name (empty string returns all categories)
Returns: If category is empty: overview with tool counts If category is specified: {category, name, tools, workflow, hint}
Inputs: category.
ds_list_datasourcesA
List the data sources of one type that the current user can see (read-only).
Pass the returned id as datasource_id of SQL tasks, e.g. in
ds_create_workflow or ds_create_dag_workflow.
Args: ds_type: Data source type in DolphinScheduler's upper-case form, e.g. HIVE (default), MYSQL, POSTGRESQL, SPARK, CLICKHOUSE.
Returns: [{"id": int, "name": str, "type": str}, ...]; empty if none match.
Inputs: ds_type.
ds_list_process_instancesA
List process instances (filter by workflow_code, state).
v2.0.12: merged ds_list_workflow_instances.
workflow_code=0 (default): list all recent instances in the project
workflow_code=: list instances for that specific workflow
Troubleshooting / Progress Tracking (v2.0.18): After getting instances, to understand execution details (which tasks running/failed/stuck), use ds_list_task_instances(process_instance_id=, include_full=True) to view task states:
RUNNING_EXECUTION: instance running but no details → check task list for dispatched/running tasks (RUNNING instance with empty task list is normal — DS is initializing DAG)
FAILURE: locate failed tasks → find FAILURE tasks, then check their logs Each RUNNING/FAILURE instance returned includes a next_action hint.
Args: project_name: Project name workflow_code: Process-definition code (0 = no filter, list all instances) state: State filter (FAILURE / SUCCESS / RUNNING_EXECUTION / STOP, empty = no filter) page_size: Number of items to return
Inputs: project_name (required), state, page_size, workflow_code.
ds_list_projectsA
List all projects. Returns [{id, code, name, description}].
Inputs: no named parameters.
ds_list_resourcesA
List resources (files and folders) at a given path.
Args: resource_type: Resource type — FILE / UDF / ALL (default, lists both) full_name: Path prefix filter; empty = list everything from root
Inputs: full_name, resource_type.
ds_list_schedulesA
List schedule configurations (optionally filtered by workflow_code).
v2.0.12: merged ds_list_schedules_in_project and ds_get_workflow_schedule.
workflow_code=0 (default): list all schedules in the project
workflow_code=: list schedules for that specific workflow
simplify=True: return a summary dict with has_schedule/cron/release_state
Args: project_name: Project name workflow_code: Process-definition code (0 = no filter) simplify: Return summary dict instead of raw list page_no: Page number page_size: Items per page
Inputs: project_name (required), page_no, simplify, page_size, +1 more. Returns: result
ds_list_task_instancesA
List task instances for a process instance (filter by state, optionally include full details).
v2.0.18: Added include_full parameter for detailed troubleshooting.
Args: project_name: Project name process_instance_id: Process instance ID state: State filter (FAILURE / SUCCESS / RUNNING_EXECUTION, empty = no filter) include_full: When True, returns full taskParams/SQL/script for each task (useful for detailed analysis but consumes more tokens)
Returns: List of task instances with: - Basic info: id, name, taskType, state, startTime, endTime, retryTimes - If include_full=True: also includes taskParams (SQL/script/dependency config)
Inputs: project_name (required), process_instance_id (required), state, include_full.
ds_list_tenantsA
List all tenants (useful for debugging workflow tenant_id foreign key issues).
Inputs: no named parameters.
ds_list_usersA
List all DS users (useful for debugging workflow user_id foreign key issues).
Inputs: no named parameters.
ds_list_workflowsA
List workflow definitions with pagination, search and exact-match support.
v2.0.12: merged ds_list_workflows_simple and ds_get_workflow_by_name.
Default: paginated API (auto-falls back to simple-list on failure)
search="xx": case-insensitive fuzzy match on name + description
name="xxx": exact name match (single-element list or empty list)
use_simple=True: use /process-definition/simple-list (bypasses pagination SQL)
Args: project_name: Project name page_no: Page number, starting at 1 page_size: Items per page (max recommended 100) search: Fuzzy search keyword (name + description) name: Exact workflow name match use_simple: Use simple-list endpoint when True
Inputs: project_name (required), name, search, page_no, +2 more.
ds_list_workflow_versionsA
List saved versions of a workflow definition (read-only).
Each save of the workflow creates a version. Use the returned version number with ds_rollback_workflow_version.
Args: project_name: Project name workflow_code: Workflow (process-definition) code from ds_list_workflows page_size: Maximum number of versions to return (first page, default 20)
Returns: [{"version": int, "description": str, "createTime": str, "updateTime": str}, ...]
Inputs: project_name (required), workflow_code (required), page_size.
ds_modify_workflow_dagA
Modify existing workflow DAG (add/delete/update tasks + adjust dependencies).
Implementation: read current DAG → apply operations → write back.
⚠️ Risk warning:
- Modifications create a new version; old versions preserved and rollback-able
- If workflow is running, it will be taken offline first (auto_offline=True by default)
- Auto-re-online after modification (auto_online=True by default)
- DS has no native "add single task" API; this tool simulates it via "read → modify → full update"
Args:
project_name: Project name
workflow_code: Workflow code
operations: Operation list (supports 5 action types)
auto_offline: Auto-offline before modification (default True)
auto_online: Auto-online after modification (default True)
auto_online_schedule: Auto-restore associated schedule after onlining (default True)
⚠️ DS offlines the schedule when workflow goes offline;
set False only if schedule auto-restore is not needed.
Supported operation types:
[1] Add task (add_task):
{
"action": "add_task",
"task": {
"name": "wait_upstream",
"type": "DEPENDENT",
"depend_items": [{
"project_code": 123,
"definition_code": 456,
"dep_task_code": 0, # 0=entire workflow, nonzero=specific task
"cycle": "day", # day/hour/week/month
"date_value": "today" # today/yesterday/last7days
}],
"dep_relation": "AND" # multi-dep relation: AND/OR
# other fields same as ds_create_dag_workflow
},
"connect_from": "task_a", # predecessor task name (empty=start node)
"connect_to": "task_b" # successor task name (empty=end node)
}
[2] Delete task (delete_task):
{
"action": "delete_task",
"task_name": "old_task",
"reconnect": true # auto-reconnect predecessor/successor to prevent DAG break
}
[3] Update task parameters (update_task):
{
"action": "update_task",
"task_name": "my_sql",
"updates": {
# ===== Common fields (snake_case / camelCase aliases supported) =====
"name": "new_task_name", # v2.0.11: rename node
"description": "Updated description",
"fail_retry_times": 3, # or "failRetryTimes"
"fail_retry_interval": 4, # or "failRetryInterval" (v2.0.10 fixed)
"timeout": 300, # timeout duration (minutes)
"timeout_flag": "OPEN", # or "timeoutFlag": "OPEN"/"CLOSE" or True/False
"timeout_notify_strategy": "FAILED", # or "timeoutNotifyStrategy": "FAILED"/"WARNING"
"worker_group": "default", # or "workerGroup"
"task_priority": "HIGH", # or "taskPriority": "HIGH"/"MEDIUM"/"LOW"
"delay_time": 0, # or "delayTime" (delay in minutes)
"flag": "YES", # "YES"=enabled "NO"=disabled
# ===== SQL task =====
"sql": "SELECT * FROM new_table WHERE dt='$[yyyyMMdd-1]'",
"datasource_id": 1, # or "datasource"
"sql_type": "HIVE", # "HIVE"/"MYSQL"/"POSTGRESQL" etc.
"sql_type_select": 0, # or "sqlType": 0=query 1=non-query
"pre_statements": [ # or "preStatements" (pre-SQL list)
"SET hive.exec.dynamic.partition=true",
"SET spark.sql.sources.partitionOverwriteMode=dynamic"
],
"post_statements": ["SELECT 1"], # or "postStatements" (post-SQL list)
# ===== SHELL/PYTHON task =====
"script": "#!/bin/bash
export PATH=/xxx/bin:$PATH python3 script.py", # or "rawScript"
# ===== Resource refs (usable by SHELL/PYTHON/SQL) =====
"resource_list": [67, 58], # or "resourceList" (int ID recommended)
# or ["/public/check_partition.py"] (full path, starting with /)
# ===== Local params =====
"local_params": [{"prop":"dt","value":"$[yyyyMMdd-1]"}] # or "localParams"
}
}
⚠️ resource_list format:
- Recommended: resource_id (int): [67, 58]
- Or full path (str): ["/public/check_partition.py", "/scripts/sync.py"]
- Paths must start with /, e.g. /public/xxx.py not public/xxx.py
- Use ds_list_resources() to view all resources with ids and paths
⚠️ Field naming compatibility:
- Supports both snake_case (e.g. pre_statements) and camelCase (e.g. preStatements)
- Both styles work identically; snake_case recommended
- Unrecognized fields logged in return value's ignored_fields
[4] Update node coordinates (update_location):
{
"action": "update_location",
"task_name": "my_task",
"x": 500,
"y": 300
}
[5] Adjust dependencies (update_relations):
{
"action": "update_relations",
"changes": [
{"op": "add", "from": "task_a", "to": "task_b"},
{"op": "remove", "from": "task_c", "to": "task_d"}
]
}
Returns:
{
"workflow_code": int,
"operations_applied": int,
"task_count_before": int,
"task_count_after": int,
"status": "updated",
"warning": risk notice
}
Typical scenario: append a DEPENDENT node so the workflow waits on upstream
ds_modify_workflow_dag(
project_name="my_project",
workflow_code=21505676237440,
operations=[{
"action": "add_task",
"task": {
"name": "wait_upstream_flow",
"type": "DEPENDENT",
"depend_items": [{
"project_code": 21582927260160,
"definition_code": 21505676200000,
"cycle": "day",
"date_value": "today"
}]
},
"connect_from": "", # start node
"connect_to": "existing_task_1" # connect to an existing task
}]
)
Inputs: operations (required), project_name (required), workflow_code (required), auto_online, +2 more.
ds_monitor_mastersA
Check DS master node status (verify scheduler is alive).
Inputs: no named parameters.
ds_monitor_workersA
Check DS worker node status (verify task executors are alive).
Inputs: no named parameters.
ds_offline_scheduleA
Take a schedule offline so it stops triggering new runs.
Keeps the schedule and running instances; bring it back with ds_online_schedule, or remove it with ds_delete_schedule.
Args: project_name: Project name schedule_id: Schedule ID (from ds_list_schedules)
Returns: {"schedule_id": int, "status": "OFFLINE"}
Inputs: schedule_id (required), project_name (required).
ds_online_create_fileA
Create a text file inline (no upload required).
Args: file_name: Filename without extension (e.g. "my_script") suffix: File extension without dot (e.g. "py" / "sh" / "sql") content: Text content to write current_dir: Parent directory path, default root "/" description: File description resource_type: FILE or UDF
Inputs: suffix (required), content (required), file_name (required), current_dir, +2 more.
ds_online_scheduleA
Bring a schedule online so it starts triggering workflow runs.
Needed after ds_set_schedule, which creates schedules offline. The workflow itself must be online (ds_release_workflow). Reverse with ds_offline_schedule.
Args: project_name: Project name schedule_id: Schedule ID (from ds_set_schedule or ds_list_schedules)
Returns: {"schedule_id": int, "status": "ONLINE"}
Inputs: schedule_id (required), project_name (required).
ds_pause_process_instanceA
Pause a RUNNING workflow instance (reversible; not a stop).
Tasks already running finish, no new tasks are started, and the instance ends in PAUSE state. Use ds_resume_process_instance to continue it, or ds_stop_process_instance to kill it instead.
Args: project_name: Project name process_instance_id: Instance ID (from ds_list_process_instances)
Returns: {"process_instance_id": int, "executeType": "PAUSE", "status": "submitted"}; the request is asynchronous, so check the state with ds_list_process_instances.
Inputs: project_name (required), process_instance_id (required).
ds_raw_deleteA
Send a raw DELETE request to the DolphinScheduler API (escape hatch).
Deletes are irreversible. Prefer the dedicated ds_delete_* tools; use this only for endpoints they do not cover.
Args: path: API path starting with / and excluding the /dolphinscheduler prefix, with any query string, e.g. "/projects/123/schedules/7"
Returns: DolphinScheduler's response as-is ({"code", "msg", "data", ...}); code 0 means success.
Inputs: path (required).
ds_raw_getA
Pass GET through to DolphinScheduler API (path must start with /, excluding the /dolphinscheduler prefix).
Inputs: path (required).
ds_raw_postA
Pass POST through to DolphinScheduler API.
Args: path: API path (starting with /) form_data_json: form-urlencoded params as a JSON string (choose one) json_body_json: JSON body as a JSON string (choose one)
Inputs: path (required), form_data_json, json_body_json.
ds_raw_putA
Send a raw PUT request to the DolphinScheduler API (escape hatch).
Prefer the dedicated update tools (e.g. ds_update_workflow, ds_update_schedule_cron); use this only for endpoints they do not cover.
Args: path: API path starting with / and excluding the /dolphinscheduler prefix, e.g. "/projects/123/schedules/7" form_data_json: form-urlencoded params as a JSON object string, e.g. '{"crontab": "0 0 2 * * ? *"}' (set this or json_body_json) json_body_json: JSON body as a JSON string (set this or form_data_json)
Returns: DolphinScheduler's response as-is ({"code", "msg", "data", ...}); code 0 means success.
Inputs: path (required), form_data_json, json_body_json.
ds_release_workflowA
Bring a workflow online or offline.
When bringing online (online=True), auto_online_schedule will also re-activate the associated schedule if it was taken offline (DS takes schedules offline when the workflow goes offline).
Args: project_name: Project name workflow_code: Process-definition code online: True=online, False=offline auto_online_schedule: Auto-reactivate associated schedule when going online (default True)
Returns: { "workflow_code": int, "releaseState": "ONLINE" / "OFFLINE", "schedule_action": str, "schedule_id": int, }
Inputs: project_name (required), workflow_code (required), online, auto_online_schedule.
ds_rename_projectA
Rename a project.
Args: old_name: Current project name new_name: New project name description: Optional new description; keeps the existing one if omitted
Inputs: new_name (required), old_name (required), description.
ds_rename_resourceA
Rename a resource file or folder.
⚠️ Warning: DS may implement rename as delete + recreate, which changes the resource_id. If this resource is referenced by workflow tasks, the reference will become invalid after renaming. Check references with ds_list_workflows before proceeding.
Args: resource_id: Resource ID new_name: New name (filename or folder name only, no path prefix) description: Description resource_type: FILE or UDF
Inputs: new_name (required), resource_id (required), description, resource_type.
ds_rerun_from_failureA
Resume from failed tasks (rerun only failed and pending tasks, skip succeeded ones).
Inputs: project_name (required), process_instance_id (required).
ds_rerun_process_instanceA
Rerun entire workflow instance (from the beginning).
Inputs: project_name (required), process_instance_id (required).
ds_resume_process_instanceA
Resume a workflow instance that is in PAUSE state.
Continues from where ds_pause_process_instance stopped it. Not for failed or stopped instances: use ds_rerun_from_failure or ds_rerun_process_instance.
Args: project_name: Project name process_instance_id: Instance ID (from ds_list_process_instances)
Returns: {"process_instance_id": int, "executeType": "RECOVER_SUSPENDED_PROCESS", "status": "submitted"}; the request is asynchronous.
Inputs: project_name (required), process_instance_id (required).
ds_rollback_workflow_versionA
Roll back a workflow to a specific historical version.
Args: project_name: Project name workflow_code: Process-definition code version: Target version number (from ds_list_workflow_versions)
Inputs: version (required), project_name (required), workflow_code (required).
ds_run_workflowA
Manually trigger a workflow run (brings it online first).
Args: project_name: Project name workflow_code: Process-definition code start_task_names: Optional list of task names to start from (including their downstream tasks). Leave empty to run the entire workflow. Example: ["partition_check"] starts from that task and all its successors. warning_type: NONE, SUCCESS, FAILURE (default) or ALL warning_group_id: Alert group ID; positive when alerts are enabled
Inputs: project_name (required), workflow_code (required), warning_type, start_task_names, +1 more.
ds_set_scheduleA
Create a schedule for a workflow (created OFFLINE; activate with ds_online_schedule).
v2.0.12: cron is now required (no default) to prevent silent misuse.
Args: project_name: Project name workflow_code: Process-definition code cron: Quartz 7-field expression (required, e.g. "0 0 6 * * ? *") start_time: Start time yyyy-MM-dd HH:mm:ss; defaults to today 00:00:00 end_time: End time; defaults to 2030-12-31 23:59:59 warning_type: NONE, SUCCESS, FAILURE (default) or ALL warning_group_id: Alert group ID; positive when alerts are enabled timezone_id: IANA timezone (default Asia/Shanghai)
Inputs: cron (required), project_name (required), workflow_code (required), end_time, +4 more.
ds_skip_taskA
Skip a task (mark as success without running).
⚠️ Warning: Use only for non-critical tasks (e.g., notifications). Downstream tasks will proceed as if this task succeeded.
Inputs: project_name (required), task_instance_id (required).
ds_stop_process_instanceA
Stop a running workflow instance (force kill).
Inputs: project_name (required), process_instance_id (required).
ds_test_connectionA
Test DolphinScheduler login and connectivity.
Inputs: no named parameters.
ds_update_resource_contentA
Update resource file content (text files only).
⚠️ Changes take effect immediately. Workflows referencing this script will use the new version on their next execution.
Args: resource_id: Resource ID content: New file content description: Update note (optional)
Inputs: content (required), resource_id (required), description.
ds_update_schedule_alertsA
Add missing alerts only; preserve schedule/definition/task configuration.
Existing FAILURE/ALL with a positive group is skipped, never overwritten. Failures return status=failed with last confirmed state and write receipts; UNKNOWN means a write may have reached DS. Never retry an unknown write. No definition release, workflow run, schedule creation/deletion or rollback.
Inputs: schedule_id (required), project_name (required), warning_type, restore_online, +1 more.
ds_update_schedule_cronA
Update only the cron expression of a schedule (keeps all other settings).
Flow: read current state → offline if needed → update → re-online (default).
v2.0.10: queries the target schedule directly instead of scanning the full list.
Args: project_name: Project name schedule_id: Schedule ID (from ds_list_schedules) cron: New Quartz 7-field expression start_time: New start time yyyy-MM-dd HH:mm:ss (keep original if empty) end_time: New end time (keep original if empty) auto_online: Re-activate after update (default True)
Returns: { "schedule_id": int, "new_cron": str, "release_state": "ONLINE" | "OFFLINE", "status": "updated", "online_retry_detail": str }
Inputs: cron (required), schedule_id (required), project_name (required), end_time, +2 more.
ds_update_task_paramA
Lightweight single-task parameter update — no need to pass full DAG definition.
This tool is a convenience wrapper around ds_modify_workflow_dag's update_task, automatically handling the "read → modify → write → online/offline" flow.
Use case: Change a single task's SQL/script/name/retry params without constructing a full operations list.
Args: project_name: Project name workflow_code: Workflow code task_name: Task name to modify (exact match) updates: Fields to update (flat dict, field names same as update_task's updates) auto_offline: Auto-offline before modification (default True) auto_online: Auto-online after modification (default True) auto_online_schedule: Auto-restore schedule after onlining (default True, v2.0.11)
Supported updates fields (snake_case and camelCase both accepted): Common: name, description, fail_retry_times(failRetryTimes), fail_retry_interval(failRetryInterval), timeout, timeout_flag(timeoutFlag), timeout_notify_strategy(timeoutNotifyStrategy), worker_group(workerGroup), task_priority(taskPriority), delay_time(delayTime), flag SQL: sql, datasource_id(datasource), sql_type, sql_type_select(sqlType), pre_statements(preStatements), post_statements(postStatements), local_params(localParams), resource_list(resourceList) SHELL/PYTHON: script(rawScript), resource_list(resourceList), local_params(localParams)
⚠️ Unrecognized fields are reported in the return value's ignored_fields (not silently dropped).
Returns: { "workflow_code": int, "task_name": str, "schedule_action": str, "status": "updated", }
Examples: # Change a single task's retry params ds_update_task_param( project_name="my_project", workflow_code=21583255237888, task_name="check_partition", updates={"fail_retry_times": 8, "fail_retry_interval": 1} )
# Rename a task (v2.0.11)
ds_update_task_param(
project_name="my_project", workflow_code=..., task_name="old_sql",
updates={"name": "new_sql_v2"}
)
# Change SQL only
ds_update_task_param(
project_name="my_project", workflow_code=..., task_name="sql1",
updates={"sql": "SELECT * FROM new_table WHERE dt='$[yyyyMMdd-1]'"}
)
Inputs: updates (required), task_name (required), project_name (required), workflow_code (required), +3 more.
ds_update_workflowA
Update workflow definition (PUT method, preserves code, auto-increments version).
This is a fallback when ds_modify_workflow_dag cannot handle the change. Supports full task definition override with complete replacement.
Args: project_name: Project name workflow_code: Process-definition code task_definitions: Task definition list (list or JSON string) task_relations: Task relation list (list or JSON string) locations: Node coordinates (list or JSON string, default "[]") name: Workflow name (empty = keep original) description: Description (empty = keep original) auto_offline: Auto-offline before update (default True) auto_online: Auto-online after update (default True)
Inputs: project_name (required), workflow_code (required), task_relations (required), task_definitions (required), +5 more.
ds_upload_fileA
Upload a file to the resource area (supports binary, e.g. jar / zip).
Two ways to provide file content: Method 1: local_path — path to a file accessible by the MCP server process Method 2: file_name + file_content_base64 — base64-encoded content
Args: local_path: Local file path (Method 1) file_name: Filename with extension (Method 2) file_content_base64: Base64-encoded file content (Method 2) current_dir: Parent directory path, default root "/" resource_type: FILE or UDF
Inputs: file_name, local_path, current_dir, resource_type, +1 more.
ds_view_resourceA
View resource file content (paginated, text files only).
Args: resource_id: Resource ID (from ds_list_resources or ds_get_resource_by_name) skip_line_num: Number of lines to skip limit: Max lines to read
Inputs: resource_id (required), limit, skip_line_num.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 60 tools
Several tool clusters overlap heavily: ds_create_workflow vs ds_create_dag_workflow (explicitly 'mode 1/mode 2' of the same action), ds_update_task_param vs ds_modify_workflow_dag's update_task vs ds_update_workflow, and ds_force_task_success vs ds_skip_task which both mark a task successful without running it. The long descriptions clarify the boundaries, but an agent still has to reason carefully to pick the right mutation tool, and the raw_* passthroughs compete with the dedicated tools.
Every tool uses the same ds_ prefix followed by a verb_noun construction (ds_list_workflows, ds_create_project, ds_delete_resource, ds_rerun_from_failure). Naming is uniform across all 60 tools with no camelCase or style mixing, and the ds_ prefix cleanly separates domain tools from helpers like ds_help.
60 tools is far beyond a comfortable surface for one server, even for a broad platform like DolphinScheduler covering projects, workflows, DAGs, instances, schedules, resources, monitoring and raw HTTP. The four raw_* passthroughs plus a help tool plus near-duplicate create/modify variants inflate the set; the surface would be stronger consolidated.
Coverage is genuinely deep: full CRUD on projects, workflows/DAGs, instances, schedules and resources, plus versions/rollback, cloning, backfill, logs, alert config and an escape hatch. Minor gaps remain, such as no user/tenant/worker-group creation and no deletion of individual task instances, but these are workable around via raw tools.
Maintenance
Related MCP Connectors
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Related MCP Servers
AlicenseAqualityFmaintenanceAn MCP server that enables AI assistants to interact with Apache Airflow's REST API for DAG management, task monitoring, and system diagnostics. It provides comprehensive tools for triggering workflows, retrieving logs, and inspecting system health across Airflow 2.x and 3.x versions.3113Apache 2.0- AlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that wraps the Apache Airflow REST API, enabling clients to manage DAGs, monitor task instances, and handle workflows through a standardized interface. It provides comprehensive access to Airflow features including DAG runs, variables, connections, and XComs.MIT
- AlicenseAqualityBmaintenanceEnables Claude to inspect and operate Apache Airflow over its REST API, providing read tools and safe write operations (gated by read-only mode) for managing DAGs, runs, tasks, and pools.14MIT

dolphin-mcp-pilotofficial
AlicenseBqualityBmaintenanceProduction-ready MCP server for Apache DolphinScheduler. Enables AI agents to operate data workflows end-to-end with 58 tools covering DAG creation, schedule management, instance control, guided troubleshooting, serial backfills, and version rollback.5824Apache 2.0