@itapi-core/mcp-n8n

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

이 서버를 사용하면 Claude, Cursor 등의 환경에서 n8n의 Workflow(워크플로우), Credential(자격 증명), Node(노드), Execution(실행 이력), Variable(글로벌 변수), Tag(태그)를 조회하고 관리(CRUD)할 수 있습니다.

Supported n8n Version (호환 버전 안내)

이 서버는 n8n 최신 버전 (2.22.2 이상 기준) 환경에 맞춰 작성되었습니다. 따라서 n8n 2.22.2 이상의 최신 버전 환경에서 가장 완벽하게 동작하며, Public REST API (/api/v1)가 활성화된 모든 환경을 지원합니다. 버전 업데이트에 따른 API 변경 시에도 호환성을 유지할 수 있도록 설계되었습니다.

Capabilities

이 서버는 다음과 같은 기능(Tools)을 제공합니다:

1. Workflow CRUD (워크플로우 관리)

• n8n_list_workflows: 전체 워크플로우 목록 조회
• n8n_get_workflow: 특정 워크플로우 상세 정보 조회
• n8n_create_workflow: 신규 워크플로우 생성
• n8n_update_workflow: 기존 워크플로우 업데이트 (이름, 노드, 설정 등)
• n8n_delete_workflow: 특정 워크플로우 삭제
• n8n_activate_workflow: 특정 워크플로우 활성화
• n8n_deactivate_workflow: 특정 워크플로우 비활성화
• n8n_backup_workflows: 전체 워크플로우를 로컬 JSON 파일로 백업
• n8n_restore_workflows: 로컬 JSON 백업 파일에서 워크플로우 복구

2. Credential CRUD (크리덴셜/인증 관리)

• n8n_list_credentials: 등록된 인증 정보 목록 조회
• n8n_get_credential: 특정 인증 정보 상세 조회
• n8n_create_credential: 새 인증 정보 등록
• n8n_update_credential: 기존 인증 정보 업데이트
• n8n_delete_credential: 특정 인증 정보 삭제

3. Node CRUD (노드 조작 - 가상 CRUD)

참고: n8n의 특성상 노드는 워크플로우에 종속되어 있습니다. 이 기능들은 내부적으로 워크플로우 데이터를 업데이트하는 방식으로 노드를 조작합니다.

• n8n_get_nodes: 특정 워크플로우 내 모든 노드 반환
• n8n_add_node: 워크플로우에 새 노드를 추가 및 저장
• n8n_update_node: 워크플로우 내 특정 노드의 설정값(파라미터 등) 수정
• n8n_delete_node: 워크플로우에서 특정 노드 및 연관된 연결선(Connections) 제거

4. Execution CRUD (실행 이력 관리)

• n8n_list_executions: 워크플로우 실행 이력 목록 조회 (limit, workflowId 필터 지원)
• n8n_get_execution: 특정 실행 이력 상세 조회
• n8n_delete_execution: 특정 실행 이력 삭제

5. Variable CRUD (글로벌 변수 관리)

• n8n_list_variables: 전역 변수 목록 조회
• n8n_create_variable: 전역 변수 생성
• n8n_update_variable: 전역 변수 수정
• n8n_delete_variable: 전역 변수 삭제

6. Tag CRUD (태그 관리)

• n8n_list_tags: 워크플로우 분류용 태그 목록 조회
• n8n_create_tag: 새 태그 생성
• n8n_update_tag: 기존 태그 이름 수정
• n8n_delete_tag: 태그 삭제

7. Generic API Request (범용 API 호출)

• n8n_api_request: 현재 툴로 지원되지 않는 n8n API 엔드포인트를 Method, Endpoint, Body 파라미터를 통해 직접 호출

Setup (환경 변수)

이 서버가 n8n API와 통신하기 위해 다음 두 가지 환경 변수가 반드시 필요합니다.

• N8N_BASE_URL: n8n 인스턴스의 주소 (예: https://n8n.yourdomain.com)
• N8N_API_KEY: n8n 설정 메뉴에서 발급받은 API 키

Usage (사용법)

npx 를 활용한 실행 (추천)

MCP를 지원하는 클라이언트(Claude Desktop, Cursor 등)의 설정 파일에 아래와 같이 추가합니다.

Cursor (cursor_mcp.json)

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-n8n"],
      "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"],
      "env": {
        "N8N_BASE_URL": "https://n8n.yourdomain.com",
        "N8N_API_KEY": "YOUR_N8N_API_KEY"
      }
    }
  }
}

Local Development (로컬 빌드 및 실행)

npm install
npm run build
npm start