n8n은 다양한 서비스와 애플리케이션을 손쉽게 연결해 워크플로를 자동화하는 도구입니다. 드래그 앤드 드롭 방식으로 여러 노드*를 추가하고 연결해 자동화 워크플로를 간편하게 만들 수 있습니다.

n8n은 워크플로 시작, 데이터 전송, 파일 처리 등을 수행하는 다양한 노드를 제공합니다. 그러나 사용자는 기본 제공 노드 외에도, ‘커뮤니티 노드’라는 나만의 맞춤형 노드를 만들어 자동화 기능을 확장할 수 있습니다.

이 글에서는 n8n 커뮤니티 노드를 개발하고 배포하는 방법을 단계별로 살펴보겠습니다(아래 영상에서 데모를 확인하세요).

*노드: 워크플로를 구성하는 개별 작업 단위

n8n 커뮤니티 노드란?​

먼저 n8n의 ‘커뮤니티 노드’ 개념과 특징을 짚고 가겠습니다. n8n은 기본적으로 여러 노드를 제공합니다. 그러나 특정 서비스나 맞춤형 기능이 필요하면 사용자가 노드를 직접 만들어 사용할 수 있습니다. 이러한 노드를 ‘커뮤니티 노드’라고 합니다. 커뮤니티 노드를 만들면, 기존 n8n의 한계를 넘어 다음 이점을 누릴 수 있습니다.

  • 특정 API나 서비스와 쉽게 연동할 수 있습니다.
  • 조직 또는 개인 요구 사항에 맞춰 자동화를 구현할 수 있습니다.
  • 다양한 자동화 기능을 추가해 오픈 소스 커뮤니티와 자동화 생태계에 기여할 수 있습니다.
2025-03-05-n8n-community-node-1-0 | 인포그랩 GitLab

기본 제공 노드는 n8n 공식 팀이 업데이트하고 유지 관리합니다. 그러나 커뮤니티 노드는 사용자 스스로 원하는 기능을 개발하고 확장할 수 있습니다.

커뮤니티 노드 제작 규칙​

n8n 공식 문서에 따르면, 커뮤니티 노드는 다음 규칙을 반드시 지켜야 합니다.

  1. 패키지 이름은 반드시 n8n-nodes- 또는 @<scope>/n8n-nodes-로 시작해야 합니다. (예: n8n-nodes-weather, @weatherPlugins/n8n-nodes-weather)
  2. 패키지 키워드에 n8n-community-node-package를 포함해야 합니다.
  3. package.json 파일의 n8n 속성 안에 node와 credential을 반드시 추가해야 합니다. (예시는 스타터 노드의 package.json을 참고)
  4. 린터를 사용해 노드를 검사하고, 로컬에서 테스트해 정상 동작을 확인해야 합니다.
  5. npm 레지스트리에 패키지를 제출해야 합니다. (자세한 내용은 npm의 ‘레지스트리에 패키지 기여하기’ 문서 참고)

이제 커뮤니티 노드를 만들어 배포하는 방법을 단계별로 알아보겠습니다.

1. 환경 설정하기​

1.1 필수 환경 설치하기​

n8n 커뮤니티 노드는 주로 TypeScript와 pnpm을 사용해 개발합니다. 먼저 개발에 필요한 도구들을 설치합니다.

  • 코드 에디터: 여기서는 Cursor로 실습합니다.
  • Node.js LTS 버전 (18.10 이상)
  • pnpm: npm install -g pnpm 명령어로 설치
  • TypeScript: pnpm install -g typescript 명령어로 설치
  • n8n: pnpm install -g n8n 명령어로 설치

1.2 npmjs.com 회원 가입하기​

커뮤니티 노드를 개발·배포하려면 npmjs.com 계정이 필요합니다. npmjs.com에 접속해 새로운 계정을 만든 뒤, 이메일 인증을 마치세요.

필자의 [npmjs.com](http://npmjs.com/) 프로필 페이지 | 인포그랩 GitLab
필자의 npmjs.com 프로필 페이지

계정을 만든 뒤, 터미널에서 npm login 명령어를 실행해 로컬 환경에서도 인증을 완료해야 합니다.

로컬에서 npm login을 실행한 모습 | 인포그랩 GitLab
로컬에서 npm login을 실행한 모습

이제 필요한 환경 설정을 마쳤습니다. 로컬 시스템에서 npm 패키지를 배포할 준비가 되었으니, 본격적으로 커뮤니티 노드 개발을 시작하겠습니다.

2. 커뮤니티 노드 프로젝트 시작하기​

n8n에서는 커뮤니티 노드를 쉽게 개발하도록 공식 템플릿을 제공합니다. 템플릿을 사용하면 프로젝트의 기본 구조를 빠르게 갖출 수 있어 매우 유용합니다.

여기서는 n8n-nodes-starter 템플릿을 개인 리포지터리로 포크해 새로운 프로젝트를 생성하는 방법을 알아보겠습니다. 프로젝트 이름은 n8n-nodes-로 시작하면 좋습니다.

2.1 템플릿 리포지터리 복제하기​

n8n-nodes-starter 공식 템플릿 리포지터리를 개인 GitHub 계정으로 가져옵니다.

[https://github.com/n8n-io/n8n-nodes-starter](https://github.com/n8n-io/n8n-nodes-starter) 화면 | 인포그랩 GitLab
https://github.com/n8n-io/n8n-nodes-starter 화면

n8n-nodes-starter 공식 템플릿을 GitHub 계정으로 포크한 뒤, 로컬 환경에 클론(Clone)합니다.

git clone https://github.com/본인계정/n8n-nodes-my-node

클론한 프로젝트 폴더로 이동한 뒤, 코드 에디터(Cursor)를 열어줍니다.

code n8n-nodes-my-node

2.2 프로젝트 구조 살펴보기​

템플릿을 다운로드하면, 다음과 같은 디렉터리 구조가 생성됩니다.

n8n-nodes-my-node/
├── src/
│   ├── nodes/          // 노드(Node) 관련 소스 코드
│   ├── credentials/    // 인증(Credential) 관련 소스 코드
├── package.json
├── tsconfig.json
└── README.md
  • src/nodes/: 노드의 코어 로직이 구현되는 폴더입니다.
  • src/credentials/: API 인증이나 OAuth 같은 보안 자격 증명을 처리하는 클래스가 포함됩니다.

이번 실습에서는 노드(Node) 코드 구현에 집중하고, Credentials 관련 내용은 이후 자세히 설명하겠습니다.

3. 노드 개발하기​

3.1 n8n 구성 요소 알아보기​

n8n의 노드는 크게 두 가지 요소로 이뤄집니다.

  1. description: 노드에 대한 기본 동작과 UI 표시 방식을 정의
  2. execute(): 실제 노드가 동작하는 로직을 담당

description에는 다음 정보가 포함됩니다.

  • displayName: n8n 에디터 UI에서 보이는 노드의 이름입니다. 사용자가 이해하기 쉬운 이름을 설정합니다.
  • name: 시스템 내부에서 사용하는 고유 식별자입니다. 소문자·카멜케이스를 사용하며, 중복되지 않아야 합니다.
  • properties: 노드 동작을 제어하는 각종 설정값(파라미터·옵션 등)을 정의합니다.
  • inputs, outputs: 노드가 받을 입력과 출력 수를 지정합니다. 기본적으로 'main'을 사용하며, 필요에 따라 여러 개를 가질 수 있습니다.
    n8n 구성 요소: icon, defaults.name, documentationUrl, credentials, inputs, outputs, properties | 인포그랩 GitLab
    n8n 구성 요소: icon, defaults.name, documentationUrl, credentials, inputs, outputs, properties

n8n 구성 요소: defaults.name, inputs, outputs, subtitle, displayName | 인포그랩 GitLab
n8n 구성 요소: defaults.name, inputs, outputs, subtitle, displayName

execute() 메서드는 노드의 핵심 로직을 처리하는 곳으로, 아래와 같이 동작합니다.

  1. this.getInputData()으로 이전 노드에서 넘어온 데이터를 가져옵니다.
  2. 필요한 처리를 수행한 뒤, 결과를 n8n에서 요구하는 배열 형태로 반환해야 합니다.

3.2 노드 클래스 정의하기​

커뮤니티 노드는 INodeType 인터페이스를 구현하는 클래스 형태로 작성합니다. 그 안에 description(노드 설명)과 execute()(실행 로직)를 정의합니다.

// nodes/SumCalculator/SumCalculator.node.ts
import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";

export class SumCalculator implements INodeType {
    description: INodeTypeDescription = {
        displayName: "Sum Calculator",
        name: "sumCalculator",
        group: ["transform"],
        version: 1,
        description: "두 수의 합을 계산하는 노드입니다",
        defaults: {
            name: "Sum Calculator",
        },
        inputs: ["main"],
        outputs: ["main"],
        properties: [
            {
                displayName: "첫 번째 숫자",
                name: "firstNumber",
                type: "number",
                default: 0,
                description: "더하기 연산의 첫 번째 숫자를 입력하세요",
                required: true,
            },
            {
                displayName: "두 번째 숫자", 
                name: "secondNumber",
                type: "number",
                default: 0,
                description: "더하기 연산의 두 번째 숫자를 입력하세요",
                required: true,
            },
        ],
    };

    async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
       ...
    }
}

3.3 노드 속성 설정하기​

노드의 description 안에 있는 properties 배열로 사용자가 에디터 UI에서 입력하거나 선택할 수 있는 파라미터와 옵션을 정의합니다. 예컨대, 아래와 같이 간단한 텍스트 입력 파라미터나 옵션 선택 파라미터 등을 설정할 수 있습니다.

예시 1: 단일 텍스트 입력 파라미터

properties: [
  {
    displayName: "Message",
    name: "message",
    type: "string",
    default: "Hello, world!",
    description: "사용자가 입력할 메시지입니다.",
  },
],
  • displayName: UI에 표시되는 필드 이름
  • name: 내부 로직에서 사용하는 식별자
  • type: 값의 유형 (string, number, boolean, options 등)
  • default: 사용자가 별도로 값을 지정하지 않았을 때 적용될 기본값
  • description: 해당 필드 설명

예시 2: 옵션 선택 파라미터

properties: [
  ...
	{
	  displayName: "Operation",
	  name: "operation",
	  type: "options",
	  options: [
	    { name: "Create", value: "create" },
	    { name: "Update", value: "update" },
	    { name: "Delete", value: "delete" },
	  ],
	  default: "create",
	  description: "어떤 작업을 수행할지 선택하세요.",
	},
],
  • type: "options"를 사용하면 드롭다운으로 여러 선택지 중 하나를 고를 수 있습니다.
  • options 내부의 name은 UI에서 보이는 텍스트이고, value는 내부 로직에서 사용할 실제 값입니다.

3.4 execute 메서드 구현하기​

execute() 메서드는 노드가 실제로 데이터를 처리하는 부분입니다. 이전 노드에서 넘어온 입력 데이터와 사용자가 정의한 노드 속성(파라미터) 값을 읽어 원하는 로직을 수행하면 됩니다.

아래는 “두 수를 입력받아 합을 반환”하는 간단한 예시입니다.

// nodes/SumCalculator/SumCalculator.node.ts
import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";

export class SumCalculator implements INodeType {
    description: INodeTypeDescription = {
        displayName: "Sum Calculator",
        name: "sumCalculator",
        group: ["transform"],
        version: 1,
        description: "두 수의 합을 계산하는 노드입니다",
        defaults: {
            name: "Sum Calculator",
        },
        inputs: ["main"],
        outputs: ["main"],
        properties: [
            {
                displayName: "첫 번째 숫자",
                name: "firstNumber",
                type: "number",
                default: 0,
                description: "더하기 연산의 첫 번째 숫자를 입력하세요",
                required: true,
            },
            {
                displayName: "두 번째 숫자", 
                name: "secondNumber",
                type: "number",
                default: 0,
                description: "더하기 연산의 두 번째 숫자를 입력하세요",
                required: true,
            },
        ],
    };

    async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
        const items = this.getInputData();
        
        for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
            // 파라미터 값 가져오기
            const firstNumber = this.getNodeParameter("firstNumber", itemIndex) as number;
            const secondNumber = this.getNodeParameter("secondNumber", itemIndex) as number;
            
            // 합계 계산
            const sum = firstNumber + secondNumber;
            
            // 결과를 JSON 데이터에 저장
            items[itemIndex].json = {
                firstNumber,
                secondNumber,
                sum,
            };
        }

        return [items];
    }
}

3.5 package.json 수정, 배포 준비하기​

커뮤니티 노드를 배포하려면 package.json에 n8n 관련 메타데이터를 반드시 추가해야 합니다. 특히 n8n.nodes에는 ‘빌드된 자바스크립트 파일 경로’를 기재해야 합니다.

아래 예시는 package.json 일부입니다.

{
	"name": "n8n-nodes-my-node",
	"version": "0.0.1",
	"description": "My Node is a sample node for n8n.",
	"keywords": [
		"n8n-community-node-package"
	],
	"license": "MIT",
	"homepage": "",
	"author": {
		"name": "Sunghun Son (Jeff)",
		"email": "sonjeff@naver.com",
		"url": "https://github.com/kaonmir"
	},
	"repository": {
		"type": "git",
		"url": "https://github.com/kaonmir/n8n-nodes-my-node.git"
	},
	"engines": {
		"node": ">=18.10",
		"pnpm": ">=9.1"
	},
	"packageManager": "pnpm@9.1.4",
	"main": "index.js",
	"scripts": {
		"preinstall": "npx only-allow pnpm",
		"build": "tsc && gulp build:icons",
		"dev": "tsc --watch",
		"format": "prettier nodes credentials --write",
		"lint": "eslint nodes credentials package.json",
		"lintfix": "eslint nodes credentials package.json --fix",
		"prepublishOnly": "pnpm build && pnpm lint -c .eslintrc.prepublish.js nodes credentials"
	},
	"files": [
		"dist"
	],
	"n8n": {
		"n8nNodesApiVersion": 1,
		"credentials": [ ],
		"nodes": [
			"dist/nodes/SumCalculator/SumCalculator.node.js"
		]
	},
	"devDependencies": { ... },
	"dependencies": { ... }
}

4. 로컬에서 실행, 테스트하기​

n8n 개발 환경에서 직접 노드를 실행하며 동작을 테스트할 수 있습니다.

  1. 터미널에서 n8n 명령을 입력해 ~/.n8n 폴더를 자동 구성합니다.
  2. ~/.n8n/nodes 커뮤니티 노드 폴더를 생성합니다.
  3. pnpm init으로 package.json을 만듭니다.
  4. pnpm link <n8n-커뮤니티-노드-경로> 명령으로 커뮤니티 노드를 연결합니다.
    • 예: pnpm link /Users/jeff/Code/github/kaonmir/n8n-nodes-my-node
  5. 커뮤니티 노드 폴더로 돌아가 npm run build && n8n 명령을 입력합니다.
  6. 브라우저에서 http://localhost:5678/ 로 접속하면, 아래 화면처럼 새로운 노드가 설치된 걸 확인할 수 있습니다.
    새로운 노드 설치 확인 화면 | 인포그랩 GitLab
    새로운 노드 설치 확인 화면

5. 배포, 공유하기​

5.1 커뮤니티 노드 배포하기​

커뮤니티 노드는 npm publish 명령어로 배포할 수 있습니다. 배포에 성공하면 패키지를 npm 사이트에서 확인할 수 있습니다.

필자가 배포한 npm 패키지 화면 | 인포그랩 GitLab
필자가 배포한 npm 패키지 화면

5.2 커뮤니티 노드를 n8n에 설치하기​

커뮤니티 노드를 n8n에 설치하는 방법은 크게 두 가지입니다.

  1. 명령어 기반 설치: 로컬 환경의 ~/.n8n/nodes 폴더에서 npm install n8n-nodes-… 명령으로 패키지를 설치합니다.
  2. UI 기반 설치: n8n 에디터 화면에서 Settings > Community nodes로 이동한 뒤, ‘Install’ 버튼을 클릭하고 원하는 npm 패키지 이름을 입력해 설치합니다.
    n8n Community nodes 설정 화면 | 인포그랩 GitLab
    n8n Community nodes 설정 화면

맺음말​

지금까지 n8n 커뮤니티 노드를 쉽고 빠르게 만드는 방법을 알아봤습니다. 노드의 기본 구조를 이해하고, 속성(프로퍼티)을 정의하며, 실제 로직을 구현하는 과정을 단계별로 살펴봤습니다. 다음 글에서는 Credential과 Resource 등 n8n 노드를 더욱 유연하게 활용하는 방법을 깊이 있게 다뤄보겠습니다.

n8n과 함께 더 가치 있는 하루를 만들고 싶으신가요? 자동화 전문가, 인포그랩과 상담하세요!