Workflow SDK
n8n v2.47요약
Workflow SDK를 사용하면 n8n 워크플로를 코드로 기술할 수 있습니다. SDK 코드는 TypeScript의 제한된 하위 집합입니다. n8n MCP 서버의 Workflow SDK 빌더 도구는 n8n 2.12.0부터 사용할 수 있습니다.
Workflow SDK를 사용하면 n8n 워크플로를 코드로 기술할 수 있습니다.
트리거와 노드를 선언하고 .add()와 .to()로 연결한 뒤 결과를 내보냅니다.
SDK는 이 코드를 에디터가 사용하는 것과 같은 워크플로 JSON으로 변환하고 검증합니다.
SDK 코드는 TypeScript의 제한된 하위 집합입니다. n8n은 인터프리터로 코드를 읽으며, 코드가 실제로 실행되지는 않습니다.
기능 제공 여부
n8n MCP 서버의 Workflow SDK 빌더 도구는 n8n 2.12.0부터 사용할 수 있습니다.
SDK는 npm의 @n8n/workflow-sdk 패키지입니다.
MCP 빌더 도구를 사용하는 데는 이 패키지를 설치할 필요가 없습니다.
Workflow SDK를 사용하는 곳#
n8n의 세 가지 구성 요소가 Workflow SDK 코드를 읽습니다.
- n8n MCP 서버 빌더 도구.
validate_workflow는 코드를 검증하고,create_workflow_from_code는 코드를 워크플로로 저장하며,update_workflow는 기존 워크플로를 변경합니다. MCP 서버 도구 레퍼런스를 참고합니다. - n8n AI. 워크플로를 만들 때 Workflow SDK 코드를 작성합니다.
- Claude Code나 Cursor 같은 AI 코딩 에이전트. n8n MCP 서버에 연결해 사용합니다.
코드를 워크플로로 변환#
SDK 코드를 인스턴스의 워크플로로 만드는 방법은 두 가지입니다.
- n8n MCP 서버를 통해서. 코드를
validate_workflow로 보낸 뒤create_workflow_from_code로 보냅니다. 인스턴스가 코드를 파싱하므로 따로 설치할 것은 없습니다. n8n 2.12.0 이상이 필요하며, 소유자 또는 관리자가 먼저 MCP 액세스를 활성화해야 합니다. 퀵스타트에서 이 방법을 단계별로 안내합니다. - 패키지를 사용해 로컬에서. npm에서
@n8n/workflow-sdk를 설치합니다.parseWorkflowCodeToBuilder로 코드를 워크플로 JSON으로 변환한 다음validateWorkflowBuilder로 검사합니다. 그런 다음 해당 JSON으로 n8n API 또는 n8n CLI를 사용해 워크플로를 만듭니다. 파서는import줄을 허용하지 않으므로 파싱하기 전에 제거합니다. SDK README의 Convert code to workflow JSON을 참고합니다.
n8n API와 n8n CLI는 워크플로 JSON으로 작업합니다. SDK 코드는 읽지 못합니다.
코드 모양#
워크플로는 호출의 연쇄입니다. 다음 예시는 수동 트리거를 실행하고, GitHub 리포지터리를 가져온 뒤, 별 개수만 남깁니다.
import { workflow, node, trigger, expr } from '@n8n/workflow-sdk';
const start = trigger({
type: 'n8n-nodes-base.manualTrigger',
version: 1,
config: { name: 'Start' }
});
const fetchRepo = node({
type: 'n8n-nodes-base.httpRequest',
version: 4.3,
config: {
name: 'Fetch repository',
parameters: { method: 'GET', url: 'https://api.github.com/repos/n8n-io/n8n' }
}
});
const keepStars = node({
type: 'n8n-nodes-base.set',
version: 3.4,
config: {
name: 'Keep stars',
parameters: {
mode: 'manual',
includeOtherFields: false,
assignments: {
assignments: [
{ id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
]
}
}
}
});
export default workflow('github-stars', 'GitHub stars')
.add(start)
.to(fetchRepo)
.to(keepStars);
모든 파일은 export default workflow(...)로 워크플로 하나를 내보냅니다.
노드 유형과 파라미터 이름은 워크플로 JSON과 같습니다.
표현식은 에디터에서 익숙한 {{ }} 구문을 expr()로 감싸서 작성합니다.
SDK 레퍼런스#
SDK 레퍼런스는 SDK 코드와 함께 제공됩니다.
- SDK README에서 패키지 설치, 동작하는 예시, 코드를 워크플로 JSON으로 변환하는 방법을 다룹니다.
- 전체 레퍼런스는 n8n MCP 서버에서
get_workflow_sdk_reference를 호출합니다. 인스턴스가 실행 중인 SDK 버전에 맞는 빌더 함수, 언어 규칙, 패턴, 표현식을 반환합니다.
이 섹션의 문서#
- 퀵스타트: 첫 워크플로 파일을 작성하고, 검사한 뒤, 인스턴스에 생성합니다.
- AI로 빌드: AI 코딩 에이전트가 인스턴스용 Workflow SDK 코드를 작성하는 데 필요한 모든 내용을 안내합니다.
어떤 패키지인가#
@n8n/workflow-sdk는 워크플로를 기술하는 패키지입니다.
n8n 공개 API 클라이언트가 아니고, @n8n/cli 명령줄 도구도 아니며, 커스텀 노드를 만드는 프레임워크도 아닙니다.
MCP 방식에서는 n8n 인스턴스가 코드를 파싱하므로 설치할 필요가 없습니다.
코드를 로컬에서 변환하거나 에디터에서 TypeScript 타입을 사용하려면 설치합니다.
Workflow SDK는 n8n Cloud와 셀프 호스팅 인스턴스에서 모두 동작합니다.