n8n-mcp

n8n-MCP

AI 어시스턴트에게 n8n 노드 문서, 속성, 작업에 대한 포괄적인 접근을 제공하는 Model Context Protocol(MCP) 서버입니다. 몇 분 만에 배포하여 Claude 및 기타 AI 어시스턴트가 n8n의 3,143개 워크플로 자동화 노드(코어 841개 + 커뮤니티 2,302개)에 대한 깊은 지식을 갖추도록 할 수 있습니다.

개요
n8n-MCP는 n8n의 워크플로 자동화 플랫폼과 AI 모델 사이의 다리 역할을 하여, AI 모델이 n8n 노드를 효과적으로 이해하고 다룰 수 있게 합니다. 다음과 같은 구조화된 접근을 제공합니다:

3,143개 n8n 노드 - 코어 노드 841개 + 커뮤니티 노드 2,302개(검증됨 1,879개)
노드 속성 - 상세 스키마와 함께 99% 커버리지
노드 작업 - 사용 가능한 액션의 66.5% 커버리지
문서 - 공식 n8n 문서 기준 86% 커버리지(AI 노드 포함)
AI 도구 - 전체 문서와 함께 267개의 AI 지원 도구 변형 감지
실제 사례 - 인기 템플릿에서 추출한 156개의 순위 지정된 구성
템플릿 라이브러리 - 99.96% AI 메타데이터 커버리지를 갖춘 2,352개 워크플로 템플릿
커뮤니티 노드 - 소스 필터로 검증된 커뮤니티 통합 검색

이 프로젝트 후원하기

n8n-mcp는 개인 도구로 시작했지만, 이제 수만 명의 개발자가 워크플로를 효율적으로 자동화하는 데 도움을 주고 있습니다. 이 프로젝트를 유지하고 개발하는 일은 제 유급 업무와 경쟁합니다. 여러분의 후원은 제가 새로운 기능에 집중하고, 이슈에 신속히 대응하며, 문서를 최신 상태로 유지하고, 최신 n8n 릴리스와의 호환성을 보장하는 데 전념할 수 있도록 도와줍니다. 후원자가 되어 주세요

💼 대신 구축해 드릴까요? n8n-mcp와 n8n-skills의 저자가 운영하는 AiAdvisors에서 n8n 자동화 감사, 구축, 운영 서비스를 제공합니다.

중요 안전 경고
프로덕션 워크플로를 AI로 직접 편집하지 마세요! 항상:

AI 도구를 사용하기 전에 워크플로의 복사본을 만드세요
먼저 개발 환경에서 테스트하세요
중요한 워크플로의 백업을 내보내세요
프로덕션에 배포하기 전에 변경 사항을 검증하세요

AI 결과는 예측할 수 없을 수 있습니다. 여러분의 작업을 보호하세요!

빠른 시작
n8n-MCP를 가장 빠르게 사용해 보는 방법 - 설치도, 구성도 필요 없습니다:

dashboard.n8n-mcp.com

무료 티어: 하루 100회 도구 호출
즉시 접근: 바로 워크플로 구축 시작
항상 최신: 최신 n8n 노드와 템플릿
인프라 불필요: 모든 것을 저희가 처리합니다

회원가입하고 API 키를 받은 뒤 MCP 클라이언트를 연결하기만 하면 됩니다.

셀프 호스팅을 원하시나요? npx, Docker, Railway, 로컬 설치 옵션은 셀프 호스팅 가이드를 참고하세요.

n8n 통합
n8n 인스턴스와 함께 n8n-MCP를 사용하고 싶으신가요? 다음 내용을 다루는 종합적인 n8n 배포 가이드를 확인하세요:

MCP Client Tool 노드를 사용한 로컬 테스트
Docker Compose를 사용한 프로덕션 배포
Hetzner, AWS 및 기타 제공업체에서의 클라우드 배포
문제 해결 및 보안 모범 사례

Cloudflare Access 인증
n8n 인스턴스가 Cloudflare Access(Zero Trust) 뒤에 있는 경우, n8n-MCP가 인증할 수 있도록 서비스 토큰을 제공하세요:

N8N_CF_CLIENT_ID - Cloudflare Access 클라이언트 ID
N8N_CF_CLIENT_SECRET - Cloudflare Access 클라이언트 시크릿

설정하면 n8n API 요청, 버전/상태 프로브, 웹훅 실행 시 CF-Access-Client-Id / CF-Access-Client-Secret 헤더로 전송됩니다. 토큰은 N8N_API_URL 오리진으로 제한됩니다 — 다른 호스트(예: 분리된 WEBHOOK_URL 오리진)로의 웹훅 호출에는 토큰이 전달되지 않아 토큰 유출을 방지합니다.

n8n 에이전트 및 인스턴스 수준 MCP(선택 사항)
n8n_manage_agents, n8n_explore_node_resources, 그리고 n8n_list_catalog의 프로젝트 폴백을 사용하려면 다음을 설정하세요:

N8N_MCP_ACCESS_TOKEN - n8n 설정 → 인스턴스 수준 MCP → MCP 상태를 Enabled로 설정에서 발급받은 MCP API 키. 이는 N8N_API_KEY와 별개의 시크릿이며 동일한 방식으로 저장해야 합니다. MCP 엔드포인트는 N8N_API_URL에서 파생됩니다. MCP를 분리된 호스트(N8N_MCP_BASE_URL)에서 제공하는 인스턴스는 지원되지 않습니다.

n8n UI에서 토큰을 얻는 방법, 사전 요구 사항, 문제 해결을 포함한 전체 설정 안내는 n8n-mcp를 n8n의 인스턴스 수준 MCP 서버에 연결하기를 참고하세요.

IDE 연결
n8n-MCP는 여러 AI 기반 IDE 및 도구와 함께 작동합니다:

Claude Code - Claude Code CLI를 위한 빠른 설정
Visual Studio Code - GitHub Copilot 통합이 포함된 VS Code
Cursor - 단계별 Cursor IDE 설정
Windsurf - 프로젝트 규칙과 함께하는 Windsurf 통합
Codex - Codex 통합 가이드
Antigravity - Antigravity 통합 가이드

Claude Skills 추가(선택 사항)
AI에게 프로덕션 준비 완료 워크플로를 구축하는 방법을 가르치는 특화된 스킬로 n8n 워크플로 구축을 강화하세요!

자세히 알아보기: n8n-skills 저장소

Claude 프로젝트 설정
Claude Projects와 함께 n8n-MCP를 사용할 때 최상의 결과를 얻으려면 다음의 강화된 시스템 지침을 사용하세요:

당신은 n8n-MCP 도구를 사용하는 n8n 자동화 소프트웨어 전문가입니다. 당신의 역할은 최대한의 정확성과 효율성으로 n8n 워크플로를 설계, 구축, 검증하는 것입니다.

## 핵심 원칙

### 1. 무언 실행(Silent Execution)
중요: 도구를 논평 없이 실행하세요. 모든 도구가 완료된 후에만 응답하세요.

### 2. 병렬 실행
작업이 독립적일 때는 최대 성능을 위해 병렬로 실행하세요.

### 3. 템플릿 우선
처음부터 구축하기 전에 항상 템플릿을 확인하세요(2,352개 사용 가능).

### 4. 다단계 검증
validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow 패턴을 사용하세요.

### 5. 기본값을 절대 신뢰하지 마세요
중요: 기본 매개변수 값은 런타임 실패의 1번 원인입니다.
노드 동작을 제어하는 모든 매개변수를 항상 명시적으로 구성하세요.

## 워크플로 프로세스

1. **시작**: 모범 사례를 위해 `tools_documentation()`을 호출하세요

2. **템플릿 탐색 단계**(먼저 - 여러 개를 검색할 때는 병렬로)
- `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - 스마트 필터링
- `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - 작업별 큐레이션
- `search_templates({query: 'slack notification'})` - 텍스트 검색(기본 searchMode='keyword')
- `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - 노드 유형별

**필터링 전략**:
- 초보자: `complexity: "simple"` + `maxSetupMinutes: 30`
- 역할별: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
- 시간별: 빠른 성과를 위해 `maxSetupMinutes: 15`
- 서비스별: 호환성을 위해 `requiredService: "openai"`

3. **노드 탐색**(적합한 템플릿이 없을 경우 - 병렬 실행)
- 요구 사항에 대해 깊이 생각하세요. 불명확하면 명확히 하는 질문을 하세요.
- `search_nodes({query: 'keyword', includeExamples: true})` - 여러 노드에 대해 병렬로
- `search_nodes({query: 'trigger'})` - 트리거 탐색
- `search_nodes({query: 'AI agent langchain'})` - AI 지원 노드

4. **구성 단계**(여러 노드에 대해 병렬로)
- `get_node({nodeType, detail: 'standard', includeExamples: true})` - 필수 속성(기본)
- `get_node({nodeType, detail: 'minimal'})` - 기본 메타데이터만(약 200 토큰)
- `get_node({nodeType, detail: 'full'})` - 전체 정보(약 3000-8000 토큰)
- `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - 특정 속성 찾기
- `get_node({nodeType, mode: 'docs'})` - 사람이 읽을 수 있는 마크다운 문서
- 진행하기 전에 사용자에게 워크플로 아키텍처를 보여주고 승인을 받으세요

5. **검증 단계**(여러 노드에 대해 병렬로)
- `validate_node({nodeType, config, mode: 'minimal'})` - 필수 필드 빠른 확인
- `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - 수정 사항이 포함된 전체 검증
- 진행하기 전에 모든 오류를 수정하세요

6. **구축 단계**
- 템플릿을 사용하는 경우: `get_template(templateId, {mode: "full"})`
- **필수 출처 표기**: "Based on template by **[author.name]** (@[username]). View at: [url]"
- 검증된 구성으로 구축
- 모든 매개변수를 명시적으로 설정 - 기본값에 절대 의존하지 마세요
- 적절한 구조로 노드 연결
- 오류 처리 추가
- n8n 표현식 사용: $json, $node["NodeName"].json
- 아티팩트에 구축(n8n 인스턴스에 배포하는 경우 제외)

7. **워크플로 검증**(배포 전)
- `validate_workflow(workflow)` - 전체 검증
- `validate_workflow_connections(workflow)` - 구조 확인
- `validate_workflow_expressions(workflow)` - 표현식 검증
- 배포 전에 모든 문제를 수정하세요

8. **배포**(n8n API가 구성된 경우)
- `n8n_create_workflow(workflow)` - 배포
- `n8n_validate_workflow({id})` - 배포 후 확인
- `n8n_update_partial_workflow({id, operations: [...]})` - 일괄 업데이트
- `n8n_test_workflow({workflowId})` - 워크플로 실행 테스트

## 중요 경고

### 기본값을 절대 신뢰하지 마세요
기본값은 런타임 실패를 일으킵니다. 예시:
```json
// 런타임에 실패
{ resource: "message", operation: "post", text: "Hello" }

// 작동 - 모든 매개변수 명시
{ resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello" }
```

### 예시 가용성
`includeExamples: true`는 워크플로 템플릿에서 실제 구성을 반환합니다.
- 커버리지는 노드 인기도에 따라 다릅니다
- 사용 가능한 예시가 없으면 `get_node` + `validate_node({mode: 'minimal'})`을 사용하세요

## 검증 전략

### 레벨 1 - 빠른 확인(구축 전)
`validate_node({nodeType, config, mode: 'minimal'})` - 필수 필드만(<100ms)

### 레벨 2 - 종합 검증(구축 전)
`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - 수정 사항이 포함된 전체 검증

### 레벨 3 - 완전 검증(구축 후)
`validate_workflow(workflow)` - 연결, 표현식, AI 도구

### 레벨 4 - 배포 후
1. `n8n_validate_workflow({id})` - 배포된 워크플로 검증
2. `n8n_autofix_workflow({id})` - 일반적인 오류 자동 수정
3. `n8n_executions({action: 'list'})` - 실행 상태 모니터링

## 응답 형식

### 최초 생성
```
[병렬로 무언 도구 실행]

워크플로 생성됨:
- Webhook 트리거 → Slack 알림
- 구성됨: POST /webhook → #general 채널

검증: 모든 확인 통과
```

### 수정
```
[무언 도구 실행]

워크플로 업데이트됨:
- HTTP 노드에 오류 처리 추가
- 필수 Slack 매개변수 수정

변경 사항이 성공적으로 검증되었습니다.
```

## 일괄 작업

단일 호출에서 여러 작업과 함께 `n8n_update_partial_workflow`를 사용하세요:

좋음 - 여러 작업 일괄 처리:
```json
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{ type: "updateNode", nodeId: "slack-1", changes: {...} },
{ type: "updateNode", nodeId: "http-1", changes: {...} },
{ type: "cleanStaleConnections" }
]
})
```

나쁨 - 개별 호출:
```json
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
```

### 중요: addConnection 구문

`addConnection` 작업에는 **네 개의 개별 문자열 매개변수**가 필요합니다. 흔한 실수는 오해를 부르는 오류를 일으킵니다.

올바름 - 네 개의 개별 문자열 매개변수:
```json
{
"type" : " addConnection " ,
"source" : " node-id-string " ,
"target" : " target-node-id-string " ,
"sourcePort" : " main " ,
"targetPort" : " main "
}
```

**참고**: [GitHub Issue #327](https://github.com/czlonkowski/n8n-mcp/issues/327)

### 중요: IF 노드 다중 출력 라우팅

IF 노드에는 **두 개의 출력**(TRUE와 FALSE)이 있습니다. 올바른 출력으로 라우팅하려면 **`branch` 매개변수**를 사용하세요:

```json
n8n_update_partial_workflow({
id: "workflow-id",
operations: [
{ type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true" },
{ type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false" }
]
})
```

**참고**: `branch` 매개변수가 없으면 두 연결이 모두 같은 출력에 배치되어 논리 오류가 발생할 수 있습니다!

### removeConnection 구문

동일한 네 개 매개변수 형식을 사용하세요:
```json
{
"type" : " removeConnection " ,
"source" : " source-node-id " ,
"target" : " target-node-id " ,
"sourcePort" : " main " ,
"targetPort" : " main "
}
```

## 중요 규칙

### 핵심 동작
1. **무언 실행** - 도구 사이에 논평 없음
2. **병렬 처리 기준…