@itapi-core/mcp-n8n

n8n (Workflow Automation Platform) 제어를 위한 MCP (Model Context Protocol) 서버입니다.

Claude, Cursor, Windsurf 등 MCP를 지원하는 AI 환경에서 n8n의 워크플로우, 자격증명, 실행 이력, 폴더, 템플릿, 보안 감사 등을 직접 조회하고 관리할 수 있습니다.

호환 버전

• n8n 2.20.0 이상 권장 (Public REST API /api/v1 활성화 필요)
• 폴더 기능: n8n 2.19+
• 버전 히스토리: n8n 2.20+

제공 도구 (40개)

🔧 시스템

| 도구 | 설명 | |------|------| | n8n_health_check | n8n API 연결 상태 및 인스턴스 정보 확인 |

📋 워크플로우 관리

| 도구 | 설명 | |------|------| | n8n_list_workflows | 워크플로우 목록 조회 (cursor 페이지네이션, active/tags/name 필터 지원) | | n8n_get_workflow | 워크플로우 상세 조회 (mode: full/structure/minimal) | | n8n_create_workflow | 새 워크플로우 생성 | | n8n_update_full_workflow | 워크플로우 전체 교체 (nodes + connections 전부 필요) | | n8n_update_partial_workflow | diff 기반 부분 업데이트 (addNode, removeNode, updateNode, addConnection, removeConnection, updateSettings, rename, activate, deactivate) | | n8n_delete_workflow | 워크플로우 삭제 | | n8n_activate_workflow | 워크플로우 활성화 | | n8n_deactivate_workflow | 워크플로우 비활성화 | | n8n_backup_workflows | 전체 워크플로우를 로컬 JSON 파일로 백업 | | n8n_restore_workflows | JSON 백업 파일로부터 워크플로우 복구 | | n8n_validate_workflow | 워크플로우 구조 검증 (트리거 노드, 고아 노드, 연결 무결성) |

🔄 버전 관리

| 도구 | 설명 | |------|------| | n8n_workflow_versions | 버전 히스토리 조회/특정 버전 확인/이전 버전으로 롤백 (action: list/get/rollback) |

📁 폴더 관리 (n8n 2.19+)

| 도구 | 설명 | |------|------| | n8n_manage_folders | 폴더 CRUD (action: list/get/create/rename/delete) |

⚙️ 노드 조작 (가상 CRUD)

| 도구 | 설명 | |------|------| | n8n_get_nodes | 워크플로우 내 모든 노드 조회 | | n8n_add_node | 워크플로우에 노드 추가 | | n8n_update_node | 워크플로우 내 특정 노드 수정 | | n8n_delete_node | 워크플로우에서 노드 및 관련 연결선 제거 |

▶️ 실행 관리

| 도구 | 설명 | |------|------| | n8n_list_executions | 실행 이력 목록 (status 필터, cursor 페이지네이션, includeData 옵션) | | n8n_get_execution | 특정 실행 이력 상세 조회 | | n8n_delete_execution | 실행 이력 삭제 | | n8n_test_workflow | Webhook 트리거 방식으로 워크플로우 실행 테스트 |

🔑 자격증명 관리

| 도구 | 설명 | |------|------| | n8n_list_credentials | 자격증명 목록 조회 | | n8n_get_credential | 특정 자격증명 조회 (비밀 데이터는 n8n에서 마스킹) | | n8n_get_credential_schema | 자격증명 타입의 필드 스키마 조회 (예: slackApi, githubApi) | | n8n_create_credential | 자격증명 생성 | | n8n_update_credential | 자격증명 수정 | | n8n_delete_credential | 자격증명 삭제 |

🌐 변수 관리

| 도구 | 설명 | |------|------| | n8n_list_variables | 전역 변수 목록 조회 | | n8n_create_variable | 전역 변수 생성 | | n8n_update_variable | 전역 변수 수정 | | n8n_delete_variable | 전역 변수 삭제 |

🏷️ 태그 관리

| 도구 | 설명 | |------|------| | n8n_list_tags | 태그 목록 조회 | | n8n_create_tag | 태그 생성 | | n8n_update_tag | 태그 이름 수정 | | n8n_delete_tag | 태그 삭제 |

🔒 보안

| 도구 | 설명 | |------|------| | n8n_audit_instance | n8n 인스턴스 보안 감사 (노출된 자격증명, 위험 노드, 방치된 워크플로우 탐지) |

🗂️ 템플릿 (n8n.io)

| 도구 | 설명 | |------|------| | n8n_search_templates | n8n.io 커뮤니티 템플릿 검색 | | n8n_get_template | 특정 템플릿 전체 워크플로우 JSON 조회 (mode: full/workflow/info) |

🛠️ 범용 API

| 도구 | 설명 | |------|------| | n8n_api_request | 위 도구로 지원되지 않는 n8n API 엔드포인트 직접 호출 |

환경 변수 설정

| 변수명 | 필수 | 설명 | |--------|------|------| | N8N_BASE_URL | ✅ | n8n 인스턴스 주소 (예: https://n8n.yourdomain.com) | | N8N_API_KEY | ✅ | n8n 설정 → API 메뉴에서 발급한 키 |

사용법

npx (추천)

MCP를 지원하는 클라이언트의 설정 파일에 아래와 같이 추가합니다.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-n8n@latest"],
      "env": {
        "N8N_BASE_URL": "https://n8n.yourdomain.com",
        "N8N_API_KEY": "YOUR_N8N_API_KEY"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-n8n@latest"],
      "env": {
        "N8N_BASE_URL": "https://n8n.yourdomain.com",
        "N8N_API_KEY": "YOUR_N8N_API_KEY"
      }
    }
  }
}

로컬 개발

npm install -g @itapi-core/mcp-n8n

또는 소스에서 직접 빌드:

npm install
npm run build
npm start

n8n_update_partial_workflow 사용 예시

노드 추가, 연결, 설정 변경을 한 번의 호출로 처리합니다.

{
  "id": "workflow-id",
  "operations": [
    {
      "op": "addNode",
      "node": {
        "name": "HTTP Request",
        "type": "n8n-nodes-base.httpRequest",
        "typeVersion": 4,
        "position": [500, 300],
        "parameters": {
          "method": "GET",
          "url": "https://api.example.com/data"
        }
      }
    },
    {
      "op": "addConnection",
      "from": "Webhook",
      "to": "HTTP Request"
    },
    {
      "op": "rename",
      "name": "Updated Workflow Name"
    }
  ]
}

변경 이력

v2.0.0

• 아키텍처 리팩토링 (단일 파일 → 4개 모듈: index, tools, handlers, n8n-client)
• 도구 22개 → 40개로 확장
• 신규: n8n_health_check, n8n_update_partial_workflow, n8n_validate_workflow, n8n_workflow_versions, n8n_manage_folders, n8n_test_workflow, n8n_get_credential_schema, n8n_audit_instance, n8n_search_templates, n8n_get_template
• 기존 도구 개선: cursor 페이지네이션, status 필터, mode 파라미터 추가

v1.0.7

• 초기 릴리즈: 워크플로우/자격증명/노드/실행/변수/태그 CRUD