Cursor n8n Builder

Instructions

Implementation Reference

• src/tools/workflow-tools.ts:229-272 (handler)

  The handler function that executes the n8n_create_workflow tool. Validates input parameters and uses N8nApiClient to create the workflow, returning success details.

  n8n_create_workflow: async (
    client: N8nApiClient,
    args: Record<string, unknown>
  ): Promise<ToolResult> => {
    const name = args.name as string;
    const nodes = args.nodes as N8nNode[];
    const connections = args.connections as N8nConnections;
    const settings = args.settings as N8nWorkflowSettings | undefined;
  
    if (!name) {
      throw new Error('Workflow name is required');
    }
    if (!nodes || !Array.isArray(nodes)) {
      throw new Error('Nodes array is required');
    }
    if (!connections) {
      throw new Error('Connections object is required');
    }
  
    const workflow = await client.createWorkflow({
      name,
      nodes,
      connections,
      settings,
    });
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify({
            success: true,
            message: `Workflow "${workflow.name}" created successfully`,
            workflow: {
              id: workflow.id,
              name: workflow.name,
              active: workflow.active,
              nodeCount: workflow.nodes.length,
            },
          }, null, 2),
        },
      ],
    };
  },

• src/tools/workflow-tools.ts:45-85 (schema)

  ToolDefinition for n8n_create_workflow including name, description, and detailed inputSchema for validation.

  {
    name: 'n8n_create_workflow',
    description: 'Create a new workflow with nodes and connections. The workflow will be created in inactive state.',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Name of the workflow',
        },
        nodes: {
          type: 'array',
          description: 'Array of node objects. Each node needs: id, name, type, typeVersion, position [x,y], parameters',
          items: {
            type: 'object',
            properties: {
              id: { type: 'string' },
              name: { type: 'string' },
              type: { type: 'string', description: 'e.g., "n8n-nodes-base.webhook", "n8n-nodes-base.httpRequest"' },
              typeVersion: { type: 'number' },
              position: { type: 'array', items: { type: 'number' } },
              parameters: { type: 'object' },
            },
            required: ['id', 'name', 'type', 'typeVersion', 'position', 'parameters'],
          },
        },
        connections: {
          type: 'object',
          description: 'Connection mapping between nodes. Format: { "sourceNode": { "main": [[{ "node": "targetNode", "type": "main", "index": 0 }]] } }',
        },
        settings: {
          type: 'object',
          description: 'Optional workflow settings',
          properties: {
            executionOrder: { type: 'string', enum: ['v0', 'v1'] },
            timezone: { type: 'string' },
          },
        },
      },
      required: ['name', 'nodes', 'connections'],
    },

• src/server.ts:122-125 (registration)

  MCP server registration and dispatching logic for workflow tools, including n8n_create_workflow handler.

  if (name in workflowToolHandlers) {
    const handler = workflowToolHandlers[name as keyof typeof workflowToolHandlers];
    return handler(client, args);
  }

• src/tools/index.ts:12-16 (registration)

  Aggregation of all tool definitions including n8n_create_workflow schema into allTools array used by MCP server.

  export const allTools: ToolDefinition[] = [
    ...documentationTools,  // Documentation first for discoverability
    ...workflowTools,
    ...executionTools,
  ];

• src/services/n8n-api-client.ts:154-164 (helper)

  N8nApiClient method that performs the actual HTTP POST to create the workflow, called by the tool handler.

  async createWorkflow(workflow: {
    name: string;
    nodes: N8nNode[];
    connections: N8nConnections;
    settings?: N8nWorkflowSettings;
  }): Promise<N8nWorkflow> {
    return this.request<N8nWorkflow>('/workflows', {
      method: 'POST',
      body: JSON.stringify(workflow),
    });
  }