Workflows API Reference¶

interface ListWorkflowsParams {
  instance?: string;
  active?: boolean;
  tags?: string[];
  limit?: number;  // Range: 1-250
  cursor?: string; // Opaque cursor token
}

interface WorkflowListResponse {
  data: WorkflowMetadata[];
  nextCursor?: string;  // Present if more data available
}

interface WorkflowMetadata {
  id: string;
  name: string;
  active: boolean;
  createdAt: string;      // ISO 8601 timestamp
  updatedAt: string;      // ISO 8601 timestamp
  nodes?: number;         // Node count (if available)
  tags?: Tag[];           // Associated tags
}

interface Tag {
  id: string;
  name: string;
}

async function getAllWorkflows(instance?: string): Promise<WorkflowMetadata[]> {
  const allWorkflows: WorkflowMetadata[] = [];
  let cursor: string | undefined;

  do {
    const response = await callMCPTool('list_workflows', {
      instance,
      limit: 100,
      cursor
    });

    const result = JSON.parse(response.content[0].text);
    allWorkflows.push(...result.data);
    cursor = result.nextCursor;
  } while (cursor);

  return allWorkflows;
}

// Usage
const workflows = await getAllWorkflows('production');
console.log(`Total workflows: ${workflows.length}`);

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'n8n-workflow-manager',
  version: '1.0.0'
});

await client.connect(transport);

// List active production workflows
const response = await client.callTool({
  name: 'list_workflows',
  arguments: {
    instance: 'production',
    active: true,
    limit: 50
  }
});

const result = JSON.parse(response.content[0].text);
console.log(`Found ${result.data.length} active workflows`);

result.data.forEach((workflow: any) => {
  console.log(`- ${workflow.name} (${workflow.nodes} nodes)`);
});

// ✅ Good: Filter on server side
const activeWorkflows = await client.callTool({
  name: 'list_workflows',
  arguments: { active: true, instance: 'production' }
});

// ❌ Avoid: Fetch all and filter client-side
const all = await client.callTool({
  name: 'list_workflows',
  arguments: { instance: 'production' }
});
const active = all.data.filter(w => w.active);  // Wasteful!

// ✅ Good: Paginate through large result sets
let cursor: string | undefined;
const workflows: WorkflowMetadata[] = [];

do {
  const page = await list({ limit: 100, cursor });
  workflows.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);

// ❌ Avoid: Requesting everything at once
const all = await list({ limit: 9999 });  // May timeout or crash

// ✅ Good: Cache with TTL for frequently accessed data
import { LRUCache } from 'lru-cache';

const workflowCache = new LRUCache<string, WorkflowMetadata[]>({
  max: 100,
  ttl: 60_000  // 1 minute
});

async function getCachedWorkflows(instance: string): Promise<WorkflowMetadata[]> {
  const cacheKey = `workflows-${instance}`;

  if (workflowCache.has(cacheKey)) {
    return workflowCache.get(cacheKey)!;
  }

  const response = await list({ instance });
  workflowCache.set(cacheKey, response.data);
  return response.data;
}

interface CreateWorkflowParams {
  instance?: string;
  name: string;
  nodes: Node[];
  connections?: Connections;
  settings?: WorkflowSettings;
  staticData?: Record<string, any>;
  tags?: string[];
  active?: boolean;
}

interface Node {
  name: string;              // Unique within workflow
  type: string;              // e.g., "n8n-nodes-base.webhook"
  typeVersion: number;       // Node type version
  position: [number, number]; // [x, y] coordinates
  parameters?: Record<string, any>;
  credentials?: Record<string, CredentialReference>;
}

interface CredentialReference {
  id: string;
  name: string;
}

interface Connections {
  [nodeName: string]: {
    main: Array<Array<{
      node: string;
      type: string;
      index: number;
    }>>;
  };
}

interface WorkflowSettings {
  timezone?: string;
  errorWorkflow?: string;
  callerPolicy?: string;
  saveExecutionProgress?: boolean;
  saveManualExecutions?: boolean;
  saveDataErrorExecution?: 'all' | 'none';
  saveDataSuccessExecution?: 'all' | 'none';
  executionTimeout?: number;
}

interface CreateWorkflowResponse {
  id: string;
  name: string;
  active: boolean;
  nodes: Node[];
  connections: Connections;
  createdAt: string;
  updatedAt: string;
  tags?: Tag[];
  settings?: WorkflowSettings;
  staticData?: Record<string, any>;
}

function generateWebhookWorkflow(
  name: string,
  webhookPath: string,
  action: string
): CreateWorkflowParams {
  return {
    name,
    nodes: [
      {
        name: 'Webhook',
        type: 'n8n-nodes-base.webhook',
        typeVersion: 1,
        position: [250, 300],
        parameters: {
          path: webhookPath,
          responseMode: 'onReceived',
          httpMethod: 'POST'
        }
      },
      {
        name: 'Process',
        type: 'n8n-nodes-base.code',
        typeVersion: 2,
        position: [450, 300],
        parameters: {
          mode: 'runOnceForAllItems',
          jsCode: `// ${action}\nreturn $input.all();`
        }
      },
      {
        name: 'Respond',
        type: 'n8n-nodes-base.respondToWebhook',
        typeVersion: 1,
        position: [650, 300],
        parameters: {
          respondWith: 'json',
          responseBody: '={{ $json }}'
        }
      }
    ],
    connections: {
      'Webhook': {
        main: [[{ node: 'Process', type: 'main', index: 0 }]]
      },
      'Process': {
        main: [[{ node: 'Respond', type: 'main', index: 0 }]]
      }
    },
    active: false
  };
}

// Usage
const workflow = generateWebhookWorkflow(
  'Order Processing',
  'process-order',
  'Validate and store order data'
);

const result = await client.callTool({
  name: 'create_workflow',
  arguments: workflow
});

console.log(`Created workflow ${result.id}`);

function generateScheduledWorkflow(
  name: string,
  cronExpression: string,
  action: string
): CreateWorkflowParams {
  return {
    name,
    nodes: [
      {
        name: 'Schedule',
        type: 'n8n-nodes-base.scheduleTrigger',
        typeVersion: 1,
        position: [250, 300],
        parameters: {
          rule: {
            interval: [{
              field: 'cronExpression',
              expression: cronExpression
            }]
          }
        }
      },
      {
        name: 'Execute Task',
        type: 'n8n-nodes-base.code',
        typeVersion: 2,
        position: [450, 300],
        parameters: {
          jsCode: `// ${action}\nreturn [{ json: { executed: true, timestamp: new Date() } }];`
        }
      }
    ],
    connections: {
      'Schedule': {
        main: [[{ node: 'Execute Task', type: 'main', index: 0 }]]
      }
    },
    settings: {
      timezone: 'America/New_York'
    },
    active: false
  };
}

// Create daily backup at 2 AM
const backup = generateScheduledWorkflow(
  'Daily Backup',
  '0 2 * * *',
  'Backup data to cloud storage'
);

await client.callTool({
  name: 'create_workflow',
  arguments: backup
});

function validateWorkflow(workflow: CreateWorkflowParams): void {
  // Check required fields
  if (!workflow.name) {
    throw new Error('Workflow name is required');
  }

  if (!workflow.nodes || workflow.nodes.length === 0) {
    throw new Error('At least one node is required');
  }

  // Check for duplicate node names
  const names = workflow.nodes.map(n => n.name);
  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
  if (duplicates.length > 0) {
    throw new Error(`Duplicate node names: ${duplicates.join(', ')}`);
  }

  // Validate connections reference existing nodes
  if (workflow.connections) {
    for (const [source, conn] of Object.entries(workflow.connections)) {
      if (!names.includes(source)) {
        throw new Error(`Connection source '${source}' not found`);
      }
      for (const targets of conn.main) {
        for (const target of targets) {
          if (!names.includes(target.node)) {
            throw new Error(`Connection target '${target.node}' not found`);
          }
        }
      }
    }
  }

  // Check for trigger node if active
  if (workflow.active) {
    const hasTrigger = workflow.nodes.some(node =>
      node.type.includes('Trigger') || node.type.includes('webhook')
    );
    if (!hasTrigger) {
      throw new Error('Active workflows require a trigger node');
    }
  }
}

// Usage
try {
  validateWorkflow(myWorkflow);
  await createWorkflow(myWorkflow);
} catch (error) {
  console.error('Validation failed:', error.message);
}

// Multi-stage deployment pattern
async function deployWorkflow(workflow: CreateWorkflowParams) {
  // Stage 1: Create in staging
  console.log('Creating workflow in staging...');
  const staging = await createWorkflow({
    ...workflow,
    instance: 'staging',
    active: false
  });

  console.log(`Staging workflow created: ${staging.id}`);

  // Stage 2: Test in staging
  console.log('Testing in staging...');
  await activateWorkflow(staging.id, 'staging');
  await testWorkflow(staging.id, 'staging');

  // Stage 3: Deploy to production
  console.log('Deploying to production...');
  const production = await createWorkflow({
    ...workflow,
    instance: 'production',
    active: false  // Keep inactive for review
  });

  console.log(`Production workflow created: ${production.id}`);
  console.log('Review workflow before activation');

  return { staging: staging.id, production: production.id };
}

import { transformConnectionsForN8N } from './utils/validation';

// If using array format (easier to work with)
const arrayConnections = [
  { source: 'Node1', target: 'Node2', sourceOutput: 0, targetInput: 0 },
  { source: 'Node2', target: 'Node3', sourceOutput: 0, targetInput: 0 }
];

// Transform to n8n's object format
const workflow: CreateWorkflowParams = {
  name: 'My Workflow',
  nodes: [...],
  connections: transformConnectionsForN8N(arrayConnections)
};

const workflow = await client.callTool({
  name: 'get_workflow',
  arguments: {
    instance: 'production',
    id: '123'
  }
});

const wf = JSON.parse(workflow.content[0].text);
console.log(`Workflow: ${wf.name}`);
console.log(`Nodes: ${wf.nodes.length}`);
console.log(`Active: ${wf.active}`);

// Update workflow name and settings
await client.callTool({
  name: 'update_workflow',
  arguments: {
    instance: 'production',
    id: '123',
    name: 'Updated Workflow Name',
    settings: {
      timezone: 'America/Los_Angeles'
    }
  }
});

await client.callTool({
  name: 'delete_workflow',
  arguments: {
    instance: 'staging',
    id: '456'
  }
});

console.log('Workflow deleted successfully');

// Activate workflow
const result = await client.callTool({
  name: 'activate_workflow',
  arguments: {
    instance: 'production',
    id: '789'
  }
});

console.log('Workflow activated successfully');

await client.callTool({
  name: 'deactivate_workflow',
  arguments: {
    instance: 'production',
    id: '789'
  }
});

console.log('Workflow deactivated');