conductor-mcp

MCP server for Netflix Conductor Workflow Engine - enables AI assistants to interact with Conductor workflows for troubleshooting, creation, and management.

Overview

This Model Context Protocol (MCP) server provides a comprehensive interface to Netflix Conductor, allowing AI assistants like Claude to help developers:

• Troubleshoot workflows: Get detailed status, view execution history, analyze failed tasks
• Manage workflow executions: Start, pause, resume, terminate, restart, and retry workflows
• Work with workflow definitions: Create, update, and query workflow definitions
• Manage task definitions: Create, update, and query task definitions
• Search and query: Advanced search capabilities across workflow executions

Installation

npm install -g conductor-mcp

Or install locally:

npm install conductor-mcp

Configuration

The MCP server connects to your Conductor instance using environment variables:

• CONDUCTOR_SERVER_URL: Base URL of your Conductor server (default: http://localhost:8080)
• CONDUCTOR_API_PATH: API path prefix (default: /api)

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "conductor": {
      "command": "conductor-mcp",
      "env": {
        "CONDUCTOR_SERVER_URL": "http://localhost:8080",
        "CONDUCTOR_API_PATH": "/api"
      }
    }
  }
}

For a remote Conductor server:

{
  "mcpServers": {
    "conductor": {
      "command": "conductor-mcp",
      "env": {
        "CONDUCTOR_SERVER_URL": "https://conductor.yourcompany.com",
        "CONDUCTOR_API_PATH": "/api"
      }
    }
  }
}

Available Tools

Workflow Execution Management

list_workflows

List workflow executions with optional filters.

Parameters:

• workflowName (optional): Filter by workflow name/type
• status (optional): Filter by status (RUNNING, COMPLETED, FAILED, TIMED_OUT, TERMINATED, PAUSED)
• startTime (optional): Filter workflows started after this time (epoch milliseconds)
• endTime (optional): Filter workflows started before this time (epoch milliseconds)
• freeText (optional): Free text search

Example:

List all failed workflows in the last 24 hours

get_workflow_status

Get detailed status of a specific workflow execution.

Parameters:

• workflowId (required): The workflow execution ID
• includeTaskDetails (optional): Include detailed task information (default: true)

Example:

Get status of workflow abc-123-def

start_workflow

Start a new workflow execution.

Parameters:

• workflowName (required): Name of the workflow to start
• version (optional): Version of the workflow (defaults to latest)
• input (optional): Input parameters as JSON object
• correlationId (optional): Correlation ID for tracking
• priority (optional): Priority 0-99 (default: 0)

Example:

Start a new order_processing workflow with input {"orderId": "12345", "customerId": "C789"}

pause_workflow

Pause a running workflow.

Parameters:

• workflowId (required): The workflow execution ID

resume_workflow

Resume a paused workflow.

Parameters:

• workflowId (required): The workflow execution ID

terminate_workflow

Terminate a workflow execution.

Parameters:

• workflowId (required): The workflow execution ID
• reason (optional): Reason for termination

restart_workflow

Restart a workflow from the beginning.

Parameters:

• workflowId (required): The workflow execution ID
• useLatestDefinition (optional): Use latest workflow definition (default: false)

retry_workflow

Retry a failed workflow from the last failed task.

Parameters:

• workflowId (required): The workflow execution ID
• resumeSubworkflowTasks (optional): Resume subworkflow tasks (default: false)

search_workflows

Advanced search for workflow executions.

Parameters:

• query (required): Query string (e.g., 'workflowType=MyWorkflow AND status=FAILED')
• start (optional): Start index for pagination (default: 0)
• size (optional): Number of results (default: 100)
• sort (optional): Sort field and order (e.g., 'startTime:DESC')

Example:

Search for all failed payment workflows in the last week

Workflow Definition Management

get_workflow_definition

Get a workflow definition by name and version.

Parameters:

• workflowName (required): Name of the workflow
• version (optional): Version (defaults to latest)

list_workflow_definitions

List all registered workflow definitions.

Parameters:

• access (optional): Filter by access type (READ or CREATE)
• tagKey (optional): Filter by tag key
• tagValue (optional): Filter by tag value

create_workflow_definition

Create or update a workflow definition.

Parameters:

• definition (required): Complete workflow definition as JSON object
• overwrite (optional): Overwrite existing definition (default: true)

Task Management

get_task_details

Get details of a specific task execution.

Parameters:

• taskId (required): The task execution ID

get_task_logs

Get execution logs for a specific task.

Parameters:

• taskId (required): The task execution ID

update_task_status

Update the status of a task execution.

Parameters:

• taskId (required): The task execution ID
• workflowInstanceId (required): The workflow instance ID
• status (required): New status (IN_PROGRESS, FAILED, FAILED_WITH_TERMINAL_ERROR, COMPLETED)
• output (optional): Task output data
• logs (optional): Task execution logs

Task Definition Management

get_task_definition

Get a task definition by name.

Parameters:

• taskName (required): Name of the task

list_task_definitions

List all registered task definitions.

Parameters:

• access (optional): Filter by access type (READ or CREATE)

create_task_definition

Create or update a task definition.

Parameters:

• definition (required): Complete task definition as JSON object

Event Handlers

get_event_handlers

Get event handlers.

Parameters:

• event (optional): Filter by event name
• activeOnly (optional): Return only active handlers (default: true)

Usage Examples

Here are some common scenarios you can ask Claude to help with:

Troubleshooting

"Show me all failed workflows in the last hour"
"Why did workflow abc-123 fail?"
"What tasks are currently running in workflow xyz-789?"
"Show me the execution history of the payment_processing workflow"

Workflow Management

"Start a new order_processing workflow with orderId 12345"
"Pause workflow abc-123"
"Retry the failed workflow xyz-789"
"Terminate all stuck workflows"

Workflow Development

"Show me the definition of the payment_processing workflow"
"Create a new workflow definition for customer onboarding"
"List all available task definitions"
"What workflows are registered in the system?"

Development

Building from Source

git clone https://github.com/opensensor/conductor-mcp.git
cd conductor-mcp
npm install
npm run build

Running Locally

npm run build
CONDUCTOR_SERVER_URL=http://localhost:8080 node build/index.js

Watch Mode

npm run watch

Architecture

This MCP server uses:

• @modelcontextprotocol/sdk: MCP protocol implementation
• axios: HTTP client for Conductor API calls
• TypeScript: Type-safe development

The server runs on stdio transport, making it compatible with Claude Desktop and other MCP clients.

API Compatibility

This server is compatible with Netflix Conductor v3.x API. It has been tested with:

• Conductor v3.15.0
• Conductor v3.13.0

Contributing

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

License

Apache-2.0

Resources

• Netflix Conductor Documentation
• Model Context Protocol
• MCP Servers

Support

For issues and questions:

• GitHub Issues: https://github.com/opensensor/conductor-mcp/issues
• Conductor Documentation: https://conductor.netflix.com/

Acknowledgments

Built with the Model Context Protocol SDK and inspired by the Netflix Conductor workflow orchestration platform.