MCP n8n 서버

Cursor 또는 Claude에서 n8n을 운영하고 구축하세요 — 인스턴스 관리(사용자, 프로젝트, 실행, 감사) 그리고 완전한 빌더 루프: 공식 n8n 패키지에서 추출한 실제 파라미터 스키마를 가진 560개 노드 카탈로그, 저장 전 검증, 자동 수리, 롤백 및 diff가 포함된 스냅샷, 노드별 실행 디버깅, 상태 보고서, 전체 인스턴스 백업.

환경 변수 두 개만 있으면 됩니다. 로컬 머신(stdio) 또는 원격 HTTP 서버로 실행됩니다. 호스팅 계정 불필요.

🎯 토큰 최적화

이 서버는 토큰 소비를 최소화하도록 최적화되어 있습니다. MCP 서버의 가장 큰 문제 중 하나인 과도한 API 토큰 사용을 해결합니다.

최적화된 부분:

• 워크플로 목록 토큰 90% 감소 — 새로운 n8n_list_workflows_summary 엔드포인트 제공

• 필드 필터링 — 필요한 데이터만 요청 가능

• 스마트 기본값 — 쿼리당 결과 수를 100개에서 10~20개로 축소

• 지능형 경고 — 작업이 상당한 토큰을 소비할 때 알림

자세한 사용 가이드는 TOKEN_OPTIMIZATION.md를 참조하세요.

Related MCP server: n8n Workflow Builder

✨ 기능

🔄 워크플로우 관리

• 생성 및 배포: 자연어 설명으로 워크플로우 구축

• CRUD 작업: 전체 수명주기 관리(생성, 읽기, 업데이트, 삭제)

• 활성화 제어: 워크플로우를 온디맨드로 활성화/비활성화

• 프로젝트 이전: 프로젝트 간 워크플로우를 원활하게 이동

• 태그 관리: 사용자 정의 태그로 워크플로우 정리

📊 실행 모니터링

• 실시간 추적: 고급 필터로 워크플로우 실행 모니터링

• 상세 정보: 전체 실행 데이터 및 로그 접근

• 오류 복구: 실패한 실행 자동 재시도

• 정리 도구: 실행 기록 효율적 관리

🔐 자격 증명 관리

• 안전한 생성: 모든 서비스에 대한 자격증명 추가

• 스키마 탐색: 자격증명 유형에 필요한 필드 자동 탐색

• 프로젝트 격리: 자격증명을 프로젝트 간에 안전하게 이전

• 유형 지원: 모든 n8n 자격증명 유형과 호환

🧱 워크플로우 빌더

• 전체 노드 카탈로그 — 실제 스키마를 가진 560개 노드: n8n-nodes-base 및 @n8n/n8n-nodes-langchain에서 직접 추출(유형, 허용 옵션, 표시 조건, 자격증명, 최신 typeVersion을 가진 파라미터), CI로 매주 재생성. n8n_search_nodes로 검색, n8n_get_node로 검사

• 실제 검증: n8n_validate_workflow는 실제 스키마와 비교하여 확인 — 존재하지 않는 노드 유형, 누락된 필수 파라미터(조건부 필수 포함), 잘못된 옵션 값, 잘못된 typeVersion, 끊어진 연결 — 저장/활성화 전에 확인

• 표현식 린팅: = 접두어가 누락된 {{ }} 표현식과 워크플로우에 존재하지 않는 노드에 대한 참조 감지

• 자동 수리: n8n_autofix_workflow는 누락된 typeVersion/위치, 중복 이름, 끊어진 연결 및 표현식 접두어 수정 — 먼저 미리 보기, 스냅샷과 함께 적용

• 정밀 편집: n8n_update_workflow_partial은 전체 흐름을 다시 작성하지 않고 노드와 연결을 추가/제거

• 공개 템플릿: n8n.io에서 검색 및 가져오기(n8n_search_public_templates, n8n_import_public_template) + 대체용 100개 번들 템플릿

• 가이드 프롬프트: MCP 프롬프트 build-workflow와 fix-workflow는 모든 에이전트를 빌드/검증/테스트/수리 전체 루프로 안내

🔬 심층 디버깅 및 상태

• 노드별 실행 데이터: n8n_get_node_execution_data는 전체 실행을 다운로드하지 않고 하나의 노드를 통해 흐른 데이터(상태, 항목 수, 출력 샘플, 오류 세부정보)를 정확히 표시

• 디버그 루프: n8n_debug_last_error는 마지막 오류에서 실패한 노드와 메시지를 반환

• 상태 보고서: n8n_workflow_health는 최근 실행에서 워크플로우별 성공률, 실패 수, 평균 소요 시간, 마지막 실패 시각을 계산하여 가장 나쁜 것부터 정렬

🛡️ 안전망 및 실제 테스트

• 자동 스냅샷: 모든 업데이트, 부분 편집, 자동 수리 또는 삭제 전에 이전 상태가 로컬에 저장됩니다(~/.mcp-n8n/snapshots, N8N_SNAPSHOT_DIR로 설정 가능)

• 롤백: n8n_rollback_workflow는 모든 스냅샷을 복원합니다 — 삭제된 워크플로우도 재생성 가능(recreate=true)

• Diff: n8n_diff_workflow_snapshot은 롤백 결정 전에 스냅샷을 현재 상태와 비교 (추가/제거/수정된 노드, 변경된 파라미터, 연결 변경)

• 전체 인스턴스 백업: n8n_export_all_workflows는 모든 워크플로우를 JSON 파일로 저장하고 n8n_import_workflows로 복원

• 종단간 테스트: n8n_trigger_webhook은 인스턴스의 Webhook 트리거 워크플로우를 호출하고 실제 HTTP 응답을 반환하므로 에이전트가 흐름이 실제로 작동하는지 검증할 수 있습니다

🎯 번들 템플릿

• n8n.io를 사용하지 않으려면 키워드 매칭이 지원되는 로컬 시작점 100개 제공

🏗️ 운영 및 관리

• 태그: 리소스 분류 및 정리

• 변수: 중앙 집중식 환경 변수 관리

• 프로젝트: 다중 테넌트 프로젝트 지원정

• 사용자 및 권한: 완전한 접근 제어 관리

• 감사 로그: 보안 및 규정 준수 보고서 생성

🚀 빠른 시작

npm을 통한 설치 (권장)

가장 쉬운 시작 방법입니다:

npm install -g mcp-n8n

구성

1. n8n API 자격증명 가져오기:

   • n8n 인스턴스 → 설정 → n8n API로 이동

   • 새 API 키 생성

2. Claude Desktop 설정:

~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 추가:

옵션 A - 전역설치 사용 (npm install -g mcp-n8n 실행한 경우):

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS는 선택 사항입니다(기본값 all). 작업 + 생성을 원하고 사용자/프로젝트 관리 도구가 필요 없으면 core,builder를 사용하세요. 인스턴스 관리만 필요하면 admin만 사용하세요.

원격 HTTP 모드 (선택 사항)

기본적으로 서버는 stdio(로컬)로 통신합니다. 공유 원격 서버(예: Docker 또는 VPS)로 실행하려면 포트를 설정하세요:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

이렇게 하면 MCP 프로토콜이 포트 3000에서 streamable HTTP로 노출되고 GET /health 엔드포인트도 함께 제공됩니다. N8N_MCP_HTTP_TOKEN을 설정하는 것을 강력히 권장합니다: 설정하면 모든 요청에 Authorization: Bearer <token> 헤더가 필요합니다. streamable HTTP를 지원하는 모든 MCP 클라이언트를 해당 헤더와 함께 http://your-host:3000에 연결하면 됩니다.

옵션 B - npx 사용 (설치 불필요, 항상 최신 버전):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Cursor 구성:

Cursor MCP 설정(Settings → Extensions → MCP)에 추가:

권장 - npx 사용 (항상 최신 버전):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

참고: Cursor는 MCP 서버에 npx 사용을 요구합니다. -y 플래그는 패키지를 프롬프트 없이 자동으로 설치/업데이트합니다.

옵션 C - Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

/data 볼륨은 실행 간 워크플로우 스냅샷을 유지합니다.

4. Claude Desktop 또는 Cursor 재시작

💬 사용 예시

구성 완료 후 n8n 자연어로 상호작용하세요:

워크플로우 생성

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

템플릿 사용

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

워크플로우 관리

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

모니터링 및 디버깅

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

🛠️ 사용 가능한 도구

• n8n_create_workflow - 새 워크플로우 생성 (먼저 검증)

• n8n_list_workflows_summary - 토큰 효율적 목록

• n8n_list_workflows - 선택적 필드 필터링을 포함한 전체 세부정보

• n8n_get_workflow - 전체 워크플로우 JSON

• n8n_update_workflow - 필드 대체 (생략된 필드는 현재 값 유지)

• n8n_update_workflow_partial - 정밀 편집: 노드와 연결 추가/제거

• n8n_delete_workflow - 워크플로우 영구 삭제

• n8n_activate_workflow / n8n_deactivate_workflow

• n8n_transfer_workflow / 태그 도구

• n8n_list_workflow_snapshots - 이 서버를 통해 이루어진 모든 변경의 로컬 기록

• n8n_rollback_workflow - 이전 버전 복원 또는 삭제된 워크플로우 재생성

• n8n_diff_workflow_snapshot - 롤백 전에 스냅샷과 현재 상태 비교

• n8n_trigger_webhook - 웹훅 워크플로우 호출 후 실제 응답 받기

• n8n_export_all_workflows / n8n_import_workflows - 전체 인스턴스 백업 및 복원

• n8n_search_nodes / n8n_get_node - 전체 카탈로그: 실제 파라미터 스키마를 가진 560개 노드

• n8n_validate_workflow - 저장/활성화 전에 실제 스키마와 JSON 확인

• n8n_autofix_workflow - 기계적 수리: typeVersion, 위치, 중복, 끊어진 연결, 표현식 접두어

• n8n_search_public_templates / n8n_import_public_template - 공식 n8n.io 라이브러리

• n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - 번들 템플릿

13개 카테고리에 100개 템플릿 포함:

• 이커머스: Shopify 자동화, WooCommerce 지원 에이전트

• 소셜 미디어: Instagram, TikTok, LinkedIn, Twitter 자동화

• AI/채팅: 챗봇, AI 에이전트, 음성 비서

• 커뮤니케이션: WhatsApp, Telegram, 이메일 자동화

• 콘텐츠: 블로그 자동화, 비디오 생성, SEO 최적화

• 인사/채용: 이력서 선별, 후보자 소싱

• 영업/CRM: 리드 생성, 콜드 콜 파이프라인

• 금융: 주식 분석, 송장 추출

• 데이터 스크래핑: Google Maps, LinkedIn, Amazon, TikTok

• 모니터링: 웹사이트 가동 시간, 경쟁사 추적

• 생산성: 달력, Notion, 일정 자동화

• n8n_list_executions - 상태, 워크플로우, 프로젝트로 필터링

• n8n_get_execution - 상세 실행 데이터

• n8n_delete_execution - 실행 기록 삭제

• n8n_retry_execution - 실패한 실행 재시도

• n8n_debug_last_error - 마지막 오류에서 실패한 노드 + 메시지

• n8n_get_node_execution_data - 특정 노드를 통해 흐른 데이터

• n8n_workflow_health - 워크플로우별 성공률, 실패, 소요 시간

• n8n_create_credential - 새 자격증명 추가

• n8n_delete_credential - 자격증명 삭제 (소유자만 가능)

• n8n_get_credential_schema - 필수 필드 탐색

• n8n_transfer_credential - 프로젝트 간 이동

태그: 생성, 목록, 조회, 업데이트, 삭제 변수: 생성, 목록, 업데이트, 삭제 사용자: 목록, 생성, 조회, 삭제, 역할 변경 프로젝트: 생성, 목록, 업데이트, 삭제, 사용자 관리

• n8n_generate_audit - 보안 감사 보고서

• n8n_pull_source_control - 버전 관리 통합

기본적으로 61개 도구 (N8N_TOOLSETS=all). core,builder는28개를 노출합니다. MCP 프롬프트 2개(build-workflow, fix-workflow)도 포함됩니다.

📚 문서

• 빠른 시작 가이드 - 5분 만에 시작하기

• 예제 및 사용 사례 - 실제 자동화 예제

• 노드 참조 - 상세 도구 문서

• 변경 로그 - 버전 이력 및 업데이트

🏗️ 프로젝트 구조

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 개발

로컬 설치 (개발용)

로컬 변경사항을 기여하거나 테스트하려면:

1. 설정

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. 로컬 빌드로 구성

Claude Desktop의 경우, ~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor의 경우, MCP 설정에 추가하세요:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

중요: /absolute/path/to/mcp-n8n/을 복제한 저장소의 실제 절대 경로로 바꾸세요 (예: /Users/yourname/projects/mcp-n8n/).

3. 테스트

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

실행 방법

메인 스크립트를 실행하려면 다음을 실행하세요:

python main.py

테스트 방법

테스트를 실행하려면 다음을 실행하세요:

pytest test_main.py

📋 요구 사항

• Node.js: 20 이상

• n8n 인스턴스: 자체 호스팅 또는 n8n Cloud (유료 플랜)

• n8n API 키: 인증에 필요

• AI IDE: MCP를 지원하는 Claude Desktop 또는 Cursor

n8n 요구 사항

• 자체 호스팅: 전체 API 액세스 ✅

• n8n Cloud: API 액세스를 위해 유료 플랜 필요

• 버전: n8n v1.0.0+ 호환

🤝 기여

기여는 언제나 환영합니다! 자유롭게 Pull Request를 제출해 주세요.

1. 저장소를 포크하세요

2. 기능 브랜치를 생성하세요 (git checkout -b feature/AmazingFeature)

3. 변경 사항을 커밋하세요 (git commit -m 'Add some AmazingFeature')

4. 브랜치에 푸시하세요 (git push origin feature/AmazingFeature)

5. Pull Request를 여세요

📝 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• n8n - 워크플로 자동화 플랫폼

• Anthropic - Claude 및 Model Context Protocol

• Cursor - AI 기반 코드 편집기

🔗 리소스

• n8n API 문서

• Model Context Protocol

• n8n 커뮤니티

• MCP 서버 레지스트리

⚠️ 중요 참고 사항

API 액세스

• n8n Cloud는 API에 액세스하려면 유료 플랜이 필요합니다

• 자체 호스팅 n8n은 모든 플랜에서 전체 API 액세스가 가능합니다

• 일부 작업에는 소유자/관리자 권한이 필요합니다

보안

• 자격 증명이 포함된 .env 파일을 절대 커밋하지 마세요

• 민감한 데이터에는 환경 변수를 사용하세요

• API 키는 n8n 인스턴스에 대한 전체 액세스 권한을 부여합니다

• 보안을 위해 API 키를 정기적으로 교체하세요

속도 제한

• n8n API 속도 제한을 준수하세요

• 대용량 결과 집합에는 페이지네이션을 사용하세요

• 속도 제한 응답에 대한 오류 처리를 구현하세요

🐛 문제 해결

연결 문제

문제: "n8n API에 연결할 수 없음"

• N8N_BASE_URL이 올바르고 접근 가능한지 확인하세요

• API 키가 유효한지 확인하세요

• n8n 인스턴스가 실행 중인지 확인하세요

권한 오류

문제: "권한이 부족합니다"

• 일부 작업에는 소유자/관리자 역할이 필요합니다

• 사용자에게 적절한 권한이 있는지 확인하세요

• 프로젝트 수준 액세스 권한을 확인하세요

템플릿 문제

문제: "템플릿을 찾을 수 없음"

• examples/ 디렉터리가 있는지 확인하세요

• templates-metadata.json이 존재하는지 확인하세요

• 템플릿 파일 참조가 올바른지 확인하세요

💡 팁 및 모범 사례

1. 템플릿으로 시작: 사전 구축된 템플릿을 시작점으로 사용하세요

2. 태그 사용: 쉬운 관리를 위해 태그로 워크플로를 구성하세요

3. 실행 모니터링: 실패한 실행을 정기적으로 확인하세요

4. 정리: 공간을 절약하기 위해 오래된 실행 데이터를 제거하세요

5. 버전 관리: n8n의 내장 버전 관리 기능을 사용하세요

6. 먼저 테스트: 프로덕션에서 활성화하기 전에 워크플로를 테스트하세요

📧 지원

• 이슈: GitHub Issues

• 토론: GitHub Discussions

• n8n 커뮤니티: community.n8n.io

⬆ 맨 위로