n8n 커스텀 노드 만들기 - 기본 구조부터 개발 방법까지 정리

n8n 커스텀 노드 만들기 - 기본 구조부터 개발 방법까지 정리

n8n은 워크플로우 자동화를 위한 강력한 오픈소스 툴로, 기본 제공 노드 외에도 사용자가 직접 노드를 만들어 맞춤형 자동화를 구현할 수 있습니다. 이를 가능하게 하는 기능이 바로 커스텀 노드(Custom Node)인데요. 오늘은 n8n에서 커스텀 노드를 개발하고 설치하는 방법을 구조적으로 정리해보겠습니다.

n8n 커스텀 노드란?

커스텀 노드는 공식 n8n 노드에 포함되지 않은 기능을 사용자가 직접 구현할 수 있도록 해주는 확장 기능입니다. 외부 API 연동, 사내 시스템 연결, 사용자 맞춤 처리 로직 등을 작성할 수 있으며, TypeScript 또는 JavaScript 기반으로 개발됩니다.

👉 공식 문서 보기: n8n Custom Nodes Guide

기본 디렉토리 구조

• nodes/ 폴더 아래 노드 단위로 구성
• 노드 이름과 동일한 디렉토리 내에 코드 파일 작성

custom-nodes/
└── nodes/
    └── MyCustomNode/
        ├── MyCustomNode.node.ts
        └── MyCustomNode.credentials.ts (선택)

간단한 커스텀 노드 예제

import { INodeType, INodeTypeDescription, IExecuteFunctions } from 'n8n-workflow';

export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'My Custom Node',
    name: 'myCustomNode',
    group: ['transform'],
    version: 1,
    description: '커스텀 API 호출 예시',
    defaults: {
      name: 'My Custom Node',
    },
    inputs: ['main'],
    outputs: ['main'],
    properties: [
      {
        displayName: 'API URL',
        name: 'apiUrl',
        type: 'string',
        default: '',
      },
    ],
  };

  async execute(this: IExecuteFunctions) {
    const items = this.getInputData();
    const returnData = [];

    for (let i = 0; i < items.length; i++) {
      const apiUrl = this.getNodeParameter('apiUrl', i) as string;

      const response = await this.helpers.request({
        method: 'GET',
        url: apiUrl,
      });

      returnData.push({ json: response });
    }

    return this.prepareOutputData(returnData);
  }
}

👉 템플릿 자동 생성 툴 사용: n8n-node-dev CLI

설치 및 적용 방법

1. 로컬 개발 환경에서 ~/.n8n/custom 경로에 파일 저장
2. N8N_CUSTOM_EXTENSIONS 환경변수에 경로 등록
3. n8n 실행 시 자동으로 해당 노드를 인식함

👉 예시 환경변수 설정: N8N_CUSTOM_EXTENSIONS=/Users/you/.n8n/custom

n8n-node-dev 사용 팁

• npx n8n-node-dev new 명령으로 템플릿 생성
• n8n-node-dev build로 배포용 번들 생성
• 개발 중 n8n-node-dev start로 테스트 가능

👉 개발 CLI 설치: npm 페이지

주의사항 및 팁

• 커스텀 노드는 보안 검토가 없기 때문에 신뢰할 수 있는 코드만 사용
• 버전 업데이트 시 기존 노드 호환성 유지 여부 확인 필요
• 워크플로우 저장 전 커스텀 노드 적용 여부 반드시 테스트

👉 n8n 공식 포럼: n8n 커뮤니티

마무리

n8n 커스텀 노드는 공식 노드로 구현되지 않은 복잡한 요구사항을 해결하는 강력한 도구입니다. 노드 구조를 이해하고 템플릿을 활용하면 누구나 손쉽게 자신만의 기능을 확장할 수 있습니다. 반복되는 업무 자동화와 외부 시스템 연동이 필요하다면, 지금 바로 커스텀 노드를 직접 만들어보세요!

더 많은 예제와 사용자 제작 노드는 n8n 커뮤니티 노드 레포지토리, n8n 공식 문서에서 확인할 수 있습니다.