n8n-MCP

Instructions

Implementation Reference

• src/mcp/handlers-n8n-manager.ts:924-988 (handler)

  The handler function that executes the 'n8n_list_workflows' tool. Validates input using Zod schema, calls N8nApiClient.listWorkflows API, transforms response to minimal metadata (id, name, active, dates, tags, nodeCount), adds pagination info (hasMore, nextCursor).

  export async function handleListWorkflows(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
    try {
      const client = ensureApiConfigured(context);
      const input = listWorkflowsSchema.parse(args || {});
  
      // Convert tags array to comma-separated string (n8n API format)
      const tagsParam = input.tags && input.tags.length > 0
        ? input.tags.join(',')
        : undefined;
  
      const response = await client.listWorkflows({
        limit: input.limit || 100,
        cursor: input.cursor,
        active: input.active,
        tags: tagsParam as any,  // API expects string, not array
        projectId: input.projectId,
        excludePinnedData: input.excludePinnedData ?? true
      });
      
      // Strip down workflows to only essential metadata
      const minimalWorkflows = response.data.map(workflow => ({
        id: workflow.id,
        name: workflow.name,
        active: workflow.active,
        isArchived: workflow.isArchived,
        createdAt: workflow.createdAt,
        updatedAt: workflow.updatedAt,
        tags: workflow.tags || [],
        nodeCount: workflow.nodes?.length || 0
      }));
  
      return {
        success: true,
        data: {
          workflows: minimalWorkflows,
          returned: minimalWorkflows.length,
          nextCursor: response.nextCursor,
          hasMore: !!response.nextCursor,
          ...(response.nextCursor ? { 
            _note: "More workflows available. Use cursor to get next page." 
          } : {})
        }
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        return {
          success: false,
          error: 'Invalid input',
          details: { errors: error.errors }
        };
      }
      
      if (error instanceof N8nApiError) {
        return {
          success: false,
          error: getUserFriendlyErrorMessage(error),
          code: error.code
        };
      }
      
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error occurred'
      };
    }

• src/mcp/tools-n8n-manager.ts:170-203 (schema)

  ToolDefinition object defining the name, description, and inputSchema (parameters with types and descriptions) for the 'n8n_list_workflows' tool.

  {
    name: 'n8n_list_workflows',
    description: `List workflows (minimal metadata only). Returns id/name/active/dates/tags. Check hasMore/nextCursor for pagination.`,
    inputSchema: {
      type: 'object',
      properties: {
        limit: { 
          type: 'number', 
          description: 'Number of workflows to return (1-100, default: 100)' 
        },
        cursor: { 
          type: 'string', 
          description: 'Pagination cursor from previous response' 
        },
        active: { 
          type: 'boolean', 
          description: 'Filter by active status' 
        },
        tags: { 
          type: 'array', 
          items: { type: 'string' },
          description: 'Filter by tags (exact match)' 
        },
        projectId: { 
          type: 'string', 
          description: 'Filter by project ID (enterprise feature)' 
        },
        excludePinnedData: { 
          type: 'boolean', 
          description: 'Exclude pinned data from response (default: true)' 
        }
      }
    }
  },

• src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts:1-55 (schema)

  Detailed ToolDocumentation providing comprehensive usage guide, parameters, return format, examples, best practices, pitfalls, and related tools for 'n8n_list_workflows'.

  import { ToolDocumentation } from '../types';
  
  export const n8nListWorkflowsDoc: ToolDocumentation = {
    name: 'n8n_list_workflows',
    category: 'workflow_management',
    essentials: {
      description: 'List workflows (minimal metadata only - no nodes/connections). Supports pagination via cursor.',
      keyParameters: ['limit', 'active', 'tags'],
      example: 'n8n_list_workflows({limit: 20, active: true})',
      performance: 'Fast (100-300ms)',
      tips: [
        'Use cursor for pagination',
        'Filter by active status',
        'Tag filtering for organization'
      ]
    },
    full: {
      description: 'Lists workflows from n8n with powerful filtering options. Returns ONLY minimal metadata (id, name, active, dates, tags, nodeCount) - no workflow structure, nodes, or connections. Use n8n_get_workflow to fetch full workflow details.',
      parameters: {
        limit: { type: 'number', description: 'Number of workflows to return (1-100, default: 100)' },
        cursor: { type: 'string', description: 'Pagination cursor from previous response for next page' },
        active: { type: 'boolean', description: 'Filter by active/inactive status' },
        tags: { type: 'array', description: 'Filter by exact tag matches (AND logic)' },
        projectId: { type: 'string', description: 'Filter by project ID (enterprise feature)' },
        excludePinnedData: { type: 'boolean', description: 'Exclude pinned data from response (default: true)' }
      },
      returns: 'Object with: workflows array (minimal fields: id, name, active, createdAt, updatedAt, tags, nodeCount), returned (count in this response), hasMore (boolean), nextCursor (for pagination), and _note (guidance when more data exists)',
      examples: [
        'n8n_list_workflows({limit: 20}) - First 20 workflows',
        'n8n_list_workflows({active: true, tags: ["production"]}) - Active production workflows',
        'n8n_list_workflows({cursor: "abc123", limit: 50}) - Next page of results'
      ],
      useCases: [
        'Build workflow dashboards',
        'Find workflows by status',
        'Organize by tags',
        'Bulk workflow operations',
        'Generate workflow reports'
      ],
      performance: 'Very fast - typically 50-200ms. Returns only minimal metadata without workflow structure.',
      bestPractices: [
        'Always check hasMore flag to determine if pagination is needed',
        'Use cursor from previous response to get next page',
        'The returned count is NOT the total in the system',
        'Iterate with cursor until hasMore is false for complete list'
      ],
      pitfalls: [
        'Requires N8N_API_URL and N8N_API_KEY configured',
        'Maximum 100 workflows per request',
        'Server may return fewer than requested limit',
        'returned field is count of current page only, not system total'
      ],
      relatedTools: ['n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_executions']
    }
  };

• src/http-server.ts:399-400 (registration)

  Registration of n8nManagementTools array (containing n8n_list_workflows definition) to the tools list in HTTP server mode.

    tools.push(...n8nManagementTools);
  }