n8n-mcp-skill을 위한 n8n-mcp 완벽 설정 가이드

Docker 환경에서 Claude Desktop이 n8n 전문가가 되는 방법

n8n 워크플로우 자동화를 AI와 함께 사용하려는 개발자들 사이에서 MCP(Model Context Protocol)가 주목받고 있습니다. 특히 czlonkowski/n8n-mcp는 Claude가 n8n의 1,084개 노드를 완벽하게 이해하고 조작할 수 있게 해주는 강력한 MCP 서버입니다. 이 글에서는 Docker 기반 n8n 환경에서 n8n-mcp를 최적으로 설정하는 방법을 단계별로 안내하며, 특히 docker run과 docker exec 방식의 차이점과 각각의 장단점을 상세히 비교합니다.

이 가이드를 따라하면 Claude Desktop에서 n8n 워크플로우를 직접 생성하고, 노드 설정을 검증하며, 2,709개의 템플릿을 즉시 검색하여 활용할 수 있게 됩니다. 기존에 n8n-mcp-skills만 사용하고 있었다면, 이 글을 통해 실제 도구를 연결하여 n8n 자동화의 진정한 잠재력을 발휘할 수 있습니다.

Claude AI가 Docker 컨테이너를 통해 n8n 워크플로우 엔진과 연결되어 자동화 파이프라인을 구성하는 모습입니다

목 차

1. n8n-mcp란 무엇인가 | czlonkowski/n8n-mcp

czlonkowski/n8n-mcp는 Claude가 n8n 워크플로우 자동화 플랫폼과 상호작용할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. 이 프로젝트는 GitHub에서 11.9K 스타를 받을 정도로 활발하게 개발되고 있으며, 2025년 1월 기준으로 133개 이상의 릴리스가 있습니다. n8n의 버전 업데이트를 거의 실시간으로 추적하여, 최신 n8n v2.3.3까지 지원하고 있습니다.

이 MCP 서버가 제공하는 핵심 기능은 크게 두 가지로 나뉩니다.

첫째는 오프라인 기능으로, n8n API 연결 없이도 내장된 70MB SQLite 데이터베이스에서 1,084개 노드 정보, 2,709개 템플릿, 노드 스키마 및 검증 규칙을 조회할 수 있습니다.
둘째는 온라인 기능으로, n8n API를 통해 실제 워크플로우를 생성, 수정, 실행하고 템플릿을 직접 배포할 수 있습니다.

기능 분류	제공 도구	API필요여부
노드 검색 및 정보 조회	search_nodes, get_node, get_node_essentials	불필요
설정 검증	validate_node, validate_workflow	불필요
템플릿 검색 및 조회	search_templates, get_template	불필요
워크플로우 관리	n8n_create_workflow, n8n_update_partial_workflow, n8n_list_workflows	필요
워크플로우 실행	n8n_test_workflow, n8n_deploy_template	필요

[i] 참고: 오프라인 기능만으로도 노드 검색, 설정 검증, 템플릿 탐색이 가능하여 n8n 학습이나 워크플로우 설계 단계에서 유용하게 활용할 수 있습니다. 실제 n8n 인스턴스에 워크플로우를 생성, 수정, 실행하고 배포하려면 API 연결이 필요합니다.

2. n8n-mcp-skills와 n8n-mcp의 관계

많은 개발자들이 n8n-mcp-skills를 설치하고 n8n 자동화를 시작했다면, 실제로는 전체 기능의 절반만 활용하고 있을 가능성이 높습니다. n8n-mcp-skills는 Claude에게 n8n 작업 방법론을 가르치는 "교과서"이고, n8n-mcp는 Claude가 실제로 n8n과 상호작용할 수 있게 해주는 "도구 세트"입니다. 이 둘은 상호 보완적이며, 함께 사용할 때 최대 효과를 발휘합니다.

n8n-mcp-skills의 README 문서에도 "n8n-mcp MCP 서버 사용 권장"이라고 명시되어 있습니다. skills는 표현식 문법, 워크플로우 패턴, 노드 설정 가이드 등의 지식을 제공하고, n8n-mcp는 이러한 지식을 실제로 적용할 수 있는 도구를 제공합니다.

아래 다이어그램은 두 프로젝트의 상호 보완적 관계를 시각적으로 보여줍니다.

구분	n8n-mcp-skills	czlonkowski/n8n-mcp
유형	Claude Skill (지식/가이드)	MCP Server (실행 도구)
역할	n8n 작업 방법론 교육	실제 도구 제공 및 실행
제공 내용	표현식 문법, 워크플로우 패턴, 검증 가이드, 코드 작성법	search_nodes, validate_node, create_workflow 등 실행 가능한 도구
설치 위치	Claude 프로젝트 또는 스킬 폴더	Docker 컨테이너 또는 npx
의존성	n8n-mcp MCP 서버 권장	독립 실행 가능

n8n-mcp-skills와 n8n-mcp와의 상호 보완적 관계:

3. MCP 아키텍처 이해하기

n8n-mcp를 올바르게 설정하려면 MCP의 Client-Server 아키텍처를 이해해야 합니다. Claude Desktop은 MCP Client 역할을 하며, n8n-mcp는 MCP Server 역할을 합니다. 이 둘은 stdio(표준 입출력)를 통해 통신하며, n8n-mcp 서버는 다시 n8n 인스턴스와 REST API로 통신합니다.

Docker 환경에서 이 아키텍처를 구성할 때, 가장 중요한 점은 n8n-mcp 컨테이너가 n8n 인스턴스에 접근할 수 있어야 한다는 것입니다. 같은 Docker 네트워크에 있다면 컨테이너 이름으로 직접 접근할 수 있고, 그렇지 않다면 host.docker.internal을 통해 호스트 머신의 localhost에 접근해야 합니다.

flowchart TB
    subgraph CLIENT["<span style='white-space: nowrap'>Claude Desktop (MCP-Client)</span>"]
        CONFIG["claude_desktop_config.json"]
    end
    
    subgraph DOCKER["<span style='white-space: nowrap'>Docker: n8n-shared-network</span>"]
        subgraph N8N["n8n-main :5678"]
            N8N_WF["워크플로우 실행"]
            N8N_API["REST API 제공"]
        end
        
        subgraph MCP["<span style='white-space: nowrap'>n8n-mcp (MCP-Server)</span>"]
            OFFLINE["오프라인 기능<br/>(내장 SQLite)"]
            ONLINE["온라인 기능<br/>(n8n API 호출)"]
        end
        
        subgraph INFRA["기타 서비스"]
            REDIS["Redis"]
            POSTGRES["PostgreSQL"]
        end
    end
    
    CLIENT -->|"stdio 통신<br/>(docker exec)"| MCP
    MCP -->|"REST API"| N8N
    N8N --> POSTGRES
    
    classDef hidden display:none;
    
    style CLIENT fill:#e1f5fe,stroke:#01579b,min-width:600px
    style DOCKER fill:#f3e5f5,stroke:#7b1fa2,min-width:800px
    style N8N fill:#fff3e0,stroke:#e65100
    style MCP fill:#e8f5e9,stroke:#2e7d32
    style INFRA fill:#fce4ec,stroke:#c2185b

[i] 참고: Docker는 MCP Server를 "어디서 실행하느냐"의 차이일 뿐입니다. npx로 로컬에서 실행하든, Docker 컨테이너에서 실행하든, MCP Server의 기능 자체는 동일합니다. Docker를 사용하면 환경 격리, 재현 가능한 설정, 기존 인프라와의 통합이 용이해집니다.

4. Docker 실행 방식 비교: docker run vs docker exec

n8n-mcp를 Docker로 실행할 때 두 가지 방식이 있습니다.

첫째는 docker run 방식으로, Claude Desktop이 시작될 때마다 새 컨테이너를 생성하고 종료 시 삭제하는 방식입니다.
둘째는 docker exec 방식으로, docker-compose로 미리 실행해 둔 컨테이너에 연결하는 방식입니다. 기존 Docker 환경에 통합하는 경우 docker exec 방식을 강력히 권장합니다.

docker 실행 방식 비교 - docker run / docker exec:

Docker 실행 방식 비교 : docker run vs docker exec

docker run 방식 | 매번 새 컨테이너 생성

docker run 방식은 Claude Desktop이 시작될 때마다 새로운 컨테이너를 생성합니다. 기존의 Docker환경에서 n8n-mcp관련 이미지를 활용한 컨테이너가 별도로 설정되어 있는 않은 경우에 사용합니다. 그래서 환경변수에서 n8n-mcp관련 이미지 정보를 같이 설정하여 새로운 컨테이너가 생성될 때 이 도커 이미지 정보를 참조합니다. 모든 환경 변수를 claude_desktop_config.json에서 직접 관리해야 하므로 설정이 길어지고, API 키가 설정 파일에 노출되는 단점이 있습니다. 단독으로 테스트하거나 간단히 사용할 때 적합합니다.

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key-here",
        "-e", "WEBHOOK_SECURITY_MODE=moderate",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

이 방식의 특징을 정리하면 다음과 같습니다. Claude Desktop 시작 시 새 컨테이너가 생성되고, 종료 시 --rm 옵션으로 자동 삭제됩니다. 환경 변수를 Claude 설정 파일에서 직접 관리해야 하므로 설정이 복잡해지고, API 키가 설정 파일에 평문으로 저장됩니다. n8n 접근은 host.docker.internal을 통해 호스트 머신의 localhost로 우회해야 합니다.

docker exec 방식 | 기존 컨테이너 사용 - 권장

docker exec 방식은 docker-compose로 미리 실행해 둔 컨테이너에 연결합니다. 환경 변수는 docker-compose.yml에서 관리하고, API 키는 .env 파일로 분리하여 보안을 강화할 수 있습니다. Claude 설정 파일은 단 한 줄로 간결해지며, 같은 Docker 네트워크에서 n8n에 직접 접근할 수 있습니다.

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": ["exec", "-i", "n8n-mcp", "node", "/app/dist/mcp/index.js"]
    }
  }
}

이 방식의 장점은 매우 명확합니다. Claude 설정 파일이 간결해지고, API 키가 노출되지 않으며, 컨테이너가 항상 실행 상태로 유지됩니다. 같은 Docker 네트워크에서 n8n-main:5678처럼 컨테이너 이름으로 직접 접근할 수 있어 네트워크 설정도 단순해집니다.

두 방식 비교표

아래 다이어그램은 두 방식의 차이를 시각적으로 보여줍니다.

비교 항목	docker run	docker exec
컨테이너 생명주기	Claude가 관리 (시작/종료)	docker-compose가 관리 (항상 실행)
환경 변수 위치	claude_desktop_config.json	docker-compose.yml + .env
n8n 접근 URL	host.docker.internal:5678	n8n-main:5678 (컨테이너명)
네트워크	기본 bridge 네트워크	n8n-shared-network (커스텀)
Claude 설정 복잡도	복잡 (10줄 이상)	간단 (1줄)
API 키 보안	설정 파일에 노출	.env 파일로 분리
권장 상황	단독 테스트, 간단한 사용	기존 Docker 환경에 통합

원격 Docker 환경 연결 | SSH 방식

지금까지 설명한 방식은 Claude Desktop과 Docker가 같은 머신에 있는 경우입니다. 하지만 실제 운영 환경에서는 Docker가 원격 서버(예: 클라우드 VM, NAS, 홈 서버)에서 실행되는 경우가 많습니다. 이 경우 SSH를 통해 원격 Docker 컨테이너에 연결할 수 있습니다.

원격 환경 구성도

SSH를 통해 Claude Desktop이 원격 서버의 Docker 컨테이너에 연결하는 구조

SSH 키 인증 설정 (필수)

원격 연결을 위해서는 비밀번호 없이 SSH 접속이 가능해야 합니다. Claude Desktop은 대화형 비밀번호 입력을 지원하지 않기 때문입니다.

# 1. SSH 키가 없다면 생성
ssh-keygen -t ed25519

# 2. 원격 서버에 공개 키 복사
ssh-copy-id user@your-server.com

# 3. 비밀번호 없이 접속 테스트
ssh user@your-server.com "echo 연결 성공"

SSH 접속을 더 편리하게 하려면 ~/.ssh/config 파일에 호스트를 등록합니다.

Host myserver
  HostName your-server.com
  Port 22
  User your-username
  IdentityFile ~/.ssh/id_ed25519
  AddKeysToAgent yes

이후 ssh myserver로 간편하게 접속할 수 있습니다.

Claude Desktop 설정 (원격 SSH 방식)

원격 서버의 Docker에 SSH로 연결하는 설정입니다. docker 명령어의 전체 경로를 지정해야 합니다. 이는 SSH로 non-interactive shell이 실행될 때 PATH가 로드되지 않을 수 있기 때문입니다.

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "ssh",
      "args": [
        "myserver",
        "/usr/local/bin/docker", "exec", "-i", "n8n-mcp", "node", "/app/dist/mcp/index.js"
      ]
    }
  }
}

원격 서버에서 docker 경로를 확인하려면 다음 명령을 실행합니다. 만약 원격서버에 접속된 상태라면 "which docker"명령어를 직접 실행하시면 됩니다.

ssh myserver "which docker"
# 출력 예: /usr/local/bin/docker 또는 /usr/bin/docker

연결 테스트

Claude Desktop 설정 전에 터미널에서 먼저 테스트합니다.

# 원격 Docker 컨테이너 목록 확인
ssh myserver "/usr/local/bin/docker ps" | grep n8n-mcp

# MCP 서버 응답 테스트
ssh myserver "/usr/local/bin/docker exec -i n8n-mcp node /app/dist/mcp/index.js" <<< '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'

JSON 응답이 오면 연결이 정상입니다. 이후 Claude Desktop을 재시작하면 원격 n8n-mcp를 사용할 수 있습니다.

세 가지 방식 비교

비교 항목	docker run	docker exec(로컬)	SSH + docker exec(원격)
Docker 위치	로컬	로컬	원격 서버
네트워크	host.docker.internal	컨테이너 네트워크	SSH 터널
설정 복잡도	중간	간단	중간 (SSH 설정 필요)
지연 시간	없음	없음	약간 (네트워크 지연)
권장 상황	단독 테스트	로컬 Docker 환경	원격 서버 운영

5. 단계별 설치 가이드

이 섹션에서는 docker exec 방식을 기준으로 n8n-mcp를 설치하는 과정을 단계별로 안내합니다. 이미 Docker 기반 n8n 환경을 운영하고 있다면, 이 방식이 가장 효율적이고 안전합니다.

아래 다이어그램은 전체 설치 과정의 흐름을 보여줍니다.

sequenceDiagram
    autonumber
    participant User as 사용자
    participant Compose as docker-compose.yml
    participant Env as .env 파일
    participant Docker as Docker Engine
    participant Claude as Claude Desktop
    
    User->>Compose: Step 1: n8n-mcp 서비스 추가
    User->>Env: Step 2: N8N_API_KEY 설정
    Note over User: Step 3: n8n UI에서 API 키 생성
    User->>Docker: Step 4: docker compose pull n8n-mcp
    Docker-->>User: 이미지 다운로드 완료
    User->>Docker: docker compose up -d n8n-mcp
    Docker-->>User: 컨테이너 시작 완료
    User->>Claude: Step 5: claude_desktop_config.json 수정
    User->>Claude: Step 6: Claude Desktop 재시작
    Claude->>Docker: docker exec -i n8n-mcp ...
    Docker-->>Claude: MCP 연결 성공
    Note over Claude: n8n-mcp 사용 준비 완료!

Step 1 | docker-compose.yml에 n8n-mcp 서비스 추가

기존 docker-compose.yml 파일에 n8n-mcp 서비스를 추가합니다. 이 서비스는 n8n과 같은 네트워크에 있어야 하며, 환경 변수를 통해 n8n API 연결 정보를 설정합니다.

services:
  # 기존 n8n 서비스들...
  
  # ---------------------------------------------------------------------------
  # n8n-mcp (Full Version) - Claude MCP Server
  # ---------------------------------------------------------------------------
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    container_name: n8n-mcp
    restart: unless-stopped
    environment:
      - MCP_MODE=stdio
      - LOG_LEVEL=error
      - DISABLE_CONSOLE_OUTPUT=true
      - N8N_API_URL=http://n8n-main:5678
      - N8N_API_KEY=${N8N_API_KEY}
      - WEBHOOK_SECURITY_MODE=moderate
      - N8N_MCP_TELEMETRY_DISABLED=true
      - TZ=${TZ:-Asia/Seoul}
    networks:
      - n8n-shared-network

networks:
  n8n-shared-network:
    external: true
    name: n8n-shared-network

위 설정에서 주의할 점들이 있습니다.

N8N_API_URL은 같은 네트워크의 n8n 컨테이너 이름을 사용합니다. 실제 n8n 컨테이너 이름이 n8n-main이 아니라면 해당 이름으로 변경해야 합니다.
N8N_API_KEY는 .env 파일에서 로드되므로 docker-compose.yml에 직접 노출되지 않습니다.
restart: unless-stopped로 설정하여 컨테이너가 항상 실행 상태를 유지하도록 합니다.

Step 2 | .env 파일에 API 키 추가

프로젝트 루트의 .env 파일에 n8n API 키를 추가합니다. 이 파일은 반드시 .gitignore에 포함시켜 버전 관리에서 제외해야 합니다.

# n8n MCP Server API Key
N8N_API_KEY=your-n8n-api-key-here

# 기타 환경 변수들...
TZ=Asia/Seoul

Step 3 | n8n에서 API 키 생성

아직 n8n API 키가 없다면 다음 과정을 통해 생성합니다. n8n 웹 인터페이스에 접속한 후, 좌측 하단의 Settings 메뉴로 이동합니다. API 섹션에서 "Create API Key" 버튼을 클릭하고, 생성된 키를 복사하여 .env 파일에 붙여넣습니다. API 키는 최초 생성 시에만 전체 값을 볼 수 있으므로, 반드시 복사해 두어야 합니다.

Step 4 | 컨테이너 시작

이미지를 다운로드하고 컨테이너를 시작합니다.

# 최신 이미지 다운로드
docker compose pull n8n-mcp

# 서비스 시작
docker compose up -d n8n-mcp

# 실행 상태 확인
docker ps | grep n8n-mcp

컨테이너가 정상적으로 실행되면 n8n-mcp가 running 상태로 표시됩니다.

Step 5 | Claude Desktop 설정 업데이트

Claude Desktop의 설정 파일에 n8n-mcp MCP 서버를 추가합니다. 설정 파일의 위치는 운영 체제에 따라 다릅니다.

운영 체제	설정 파일 경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

설정 파일에 다음 내용을 추가합니다. 기존에 다른 MCP 서버가 설정되어 있다면 mcpServers 객체 안에 함께 추가합니다.

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": ["exec", "-i", "n8n-mcp", "node", "/app/dist/mcp/index.js"]
    }
  }
}

Step 6 | Claude Desktop 재시작

설정을 적용하려면 Claude Desktop을 완전히 종료한 후 다시 시작해야 합니다. 재시작 후 Claude에게 "n8n에서 Slack 노드를 검색해줘"라고 요청하여 연결이 정상적으로 되었는지 확인할 수 있습니다.

6. 내장 SQLite와 n8n PostgreSQL의 차이

n8n-mcp를 설정할 때 자주 발생하는 오해 중 하나가 데이터베이스에 관한 것입니다. n8n이 PostgreSQL을 사용하고 있다면, n8n-mcp도 자동으로 PostgreSQL을 사용할 것이라고 생각하기 쉽습니다. 하지만 이 둘은 완전히 별개의 데이터베이스입니다.

n8n-mcp에 내장된 SQLite 데이터베이스는 약 70MB 크기의 참조 데이터를 담고 있습니다. 이 데이터베이스에는 1,084개 n8n 노드의 스키마, 속성, 문서 정보와 2,709개 커뮤니티 템플릿 정보가 포함되어 있습니다. 이 데이터베이스는 읽기 전용이며, 사용자가 직접 수정할 수 없습니다. n8n-mcp 이미지가 업데이트될 때 자동으로 갱신됩니다.

반면 n8n의 PostgreSQL(또는 SQLite)은 실제 워크플로우 정의, 실행 이력, 크레덴셜 등 사용자 데이터를 저장합니다. n8n-mcp는 이 데이터베이스에 직접 접근하지 않고, REST API를 통해서만 n8n 데이터에 접근합니다.

flowchart TB
    subgraph MCP_CONTAINER["n8n-mcp 컨테이너"]
        subgraph SQLITE["내장 SQLite (읽기 전용)"]
            NODE_INFO["노드 스키마 및 속성 정보<br/>(1,084개 노드)"]
            NODE_DOCS["노드 문서 및 예제<br/>(87% 커버리지)"]
            TEMPLATES["템플릿 정보<br/>(2,709개)"]
            RULES["검증 규칙"]
        end
        NOTE1["[!] 이미지 업데이트 시 자동 갱신"]
        NOTE2["[!] 사용자 수정 불가"]
    end
    
    subgraph N8N_CONTAINER["n8n-main 컨테이너"]
        subgraph POSTGRES["PostgreSQL (사용자 데이터)"]
            WF_DEF["워크플로우 정의"]
            EXEC_HIST["실행 이력"]
            CREDS["크레덴셜"]
            SETTINGS["설정"]
        end
    end
    
    MCP_CONTAINER -->|"REST API 호출"| N8N_CONTAINER
    
    style MCP_CONTAINER fill:#e3f2fd,stroke:#1565c0
    style SQLITE fill:#fff8e1,stroke:#ff8f00
    style N8N_CONTAINER fill:#fce4ec,stroke:#c2185b
    style POSTGRES fill:#e8f5e9,stroke:#2e7d32

아래 SVG 이미지는 두 데이터베이스의 역할 차이를 더 직관적으로 보여줍니다.

이러한 구조 덕분에 n8n-mcp는 n8n의 데이터베이스 종류(SQLite, PostgreSQL, MySQL)와 관계없이 동일하게 작동합니다. API 키와 URL만 올바르게 설정하면 됩니다.

n8n-mcp와 n8n 데이터베이스 아키텍처:

n8n-mcp 업데이트 방법

n8n이 새 버전으로 업데이트되면, n8n-mcp도 업데이트하여 최신 노드 정보를 반영해야 합니다. czlonkowski/n8n-mcp 프로젝트는 n8n의 버전 업데이트를 매우 빠르게 추적하므로, 정기적으로 이미지를 업데이트하는 것이 좋습니다.

# 최신 이미지 다운로드
docker compose pull n8n-mcp

# 컨테이너 재시작 (새 이미지 적용)
docker compose up -d n8n-mcp

7. 기존 MCP 서버 정리 및 통합

czlonkowski/n8n-mcp (Full 버전)를 설치하면, 기존에 사용하던 일부 MCP 서버들을 제거하여 중복을 피할 수 있습니다. 아래 표는 어떤 MCP 서버를 유지하고 어떤 것을 제거할 수 있는지 정리한 것입니다. n8n-mcp와 관련된 중복되는 기능을 포함하고 있는 MCP서버를 삭제하는 것은 중복된 기능으로 인해 Claude에게 명확한 mcp의 접근 및 사용이 가능해지도록 하는 목적입니다. 중복된 기능을 수행하는 MCP서버가 있다면 사용자가 의도하지 않은 MCP가 실행되거나 실행 후 결과를 예측하기 힘들 수 있습니다.

기존 MCP	서버 제거 가능 여부	이유
n8n-workflow-builder	[v] 제거 가능	Full 버전에 동일 기능 포함 (워크플로우 CRUD, 실행, 태그 관리)
n8n-mcp (기존 간단 버전)	[v] 제거 가능	Full 버전이 상위 호환
n8n-scrap-news(예시)	[!] 유지	커스텀 워크플로우 전용 (특정 용도)
n8n-kakaotalk-to-me(예시)	[!] 유지	커스텀 워크플로우 전용 (특정 용도)

커스텀 워크플로우 전용 MCP 서버들은 특정 워크플로우를 직접 실행하기 위한 것이므로, n8n-mcp와는 용도가 다릅니다. 이러한 서버들은 계속 유지해야 합니다.

기존 n8n-mcp 및 n8n-workflow-builder 삭제 방법

czlonkowski/n8n-mcp (Full 버전)로 통합하기 전에, 기존에 설치된 n8n-mcp와 n8n-workflow-builder를 완전히 삭제하고 초기화해야 합니다. 설치 방식에 따라 정리 방법이 다르므로, 자신의 환경에 맞는 섹션을 참고하시기 바랍니다.

Case A | Docker로 설치한 경우

Docker 컨테이너로 n8n-mcp 또는 n8n-workflow-builder를 운영하고 있었다면, 다음 단계를 따릅니다.

A-1. Claude Desktop 설정에서 기존 MCP 서버 제거

먼저 Claude Desktop이 기존 MCP 서버에 연결하지 않도록 설정을 수정합니다. claude_desktop_config.json 파일을 열고 기존 n8n 관련 MCP 서버 항목을 제거합니다.

{
  "mcpServers": {
    // 아래 항목들을 삭제합니다
    "n8n-mcp": { ... },           // 삭제
    "n8n-workflow-builder": { ... } // 삭제
    
    // 커스텀 워크플로우 전용 MCP는 유지
    "n8n-scrap-news": { ... },
    "n8n-kakaotalk-to-me": { ... }
  }
}

설정 파일 수정 후 Claude Desktop을 완전히 종료합니다.

A-2. Docker 컨테이너 중지 및 삭제

기존에 Docker로 실행 중이던 컨테이너를 중지하고 삭제합니다.

# 실행 중인 컨테이너 확인
docker ps | grep -E "n8n-mcp|n8n-workflow-builder"

# 컨테이너 중지
docker stop n8n-mcp n8n-workflow-builder 2>/dev/null

# 컨테이너 삭제
docker rm n8n-mcp n8n-workflow-builder 2>/dev/null

# 삭제 확인 (아무것도 출력되지 않으면 성공)
docker ps -a | grep -E "n8n-mcp|n8n-workflow-builder"

A-3. Docker 이미지 삭제 (선택사항)

디스크 공간을 확보하고 싶다면, 기존 이미지도 삭제할 수 있습니다.

# n8n 관련 이미지 목록 확인
docker images | grep -E "n8n-mcp|n8n-workflow-builder"

# 특정 이미지 삭제 (예시)
docker rmi ghcr.io/czlonkowski/n8n-mcp:latest 2>/dev/null

# 사용하지 않는 이미지 일괄 정리 (주의: 다른 이미지도 삭제될 수 있음)
docker image prune -f

A-4. docker-compose.yml에서 서비스 제거

docker-compose.yml 파일에 기존 서비스가 정의되어 있다면 해당 섹션을 삭제하거나 주석 처리합니다.

services:
  # 아래 서비스들을 삭제하거나 주석 처리
  # n8n-mcp:
  #   image: some-old-image
  #   ...
  
  # n8n-workflow-builder:
  #   image: some-builder-image
  #   ...

Case B | npx로 로컬에 설치한 경우

npx를 통해 로컬에서 n8n-mcp 또는 n8n-workflow-builder를 실행하고 있었다면, 다음 단계를 따릅니다. npx는 패키지를 글로벌로 설치하지 않고 임시로 실행하지만, 캐시와 설정 파일이 남아있을 수 있습니다.

B-1. Claude Desktop 설정에서 기존 MCP 서버 제거

claude_desktop_config.json 파일을 열고 npx 기반 MCP 서버 항목을 제거합니다. npx 방식의 설정은 일반적으로 다음과 같은 형태입니다.

{
  "mcpServers": {
    // npx 방식 설정 예시 - 삭제 대상
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key"
      }
    },
    
    // 또는 이런 형태일 수도 있음 - 삭제 대상
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["-y", "@n8n/workflow-builder-mcp"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

위와 같은 npx 기반 항목을 모두 삭제하고, Claude Desktop을 완전히 종료합니다.

B-2. npx 캐시 삭제

npx는 실행할 때마다 패키지를 임시로 다운로드하여 캐시에 저장합니다. 이 캐시를 삭제하면 이전 버전이 남아있지 않게 됩니다.

# npx 캐시 디렉토리 확인 및 삭제 (macOS/Linux)
rm -rf ~/.npm/_npx

# npm 캐시 전체 정리 (선택사항)
npm cache clean --force

# 캐시 삭제 확인
ls ~/.npm/_npx 2>/dev/null || echo "npx 캐시가 삭제되었습니다"

Windows의 경우 다음 경로에서 캐시를 삭제합니다.

# Windows PowerShell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm cache clean --force

# 또는 cmd
rmdir /s /q "%LOCALAPPDATA%\npm-cache\_npx"

B-3. 글로벌 설치된 패키지 확인 및 삭제

혹시 npm으로 글로벌 설치했을 수도 있으니 확인하고 삭제합니다.

# 글로벌 설치된 n8n 관련 패키지 확인
npm list -g | grep -E "n8n-mcp|workflow-builder"

# 글로벌 패키지 삭제 (설치되어 있는 경우)
npm uninstall -g n8n-mcp 2>/dev/null
npm uninstall -g @n8n/workflow-builder-mcp 2>/dev/null
npm uninstall -g n8n-workflow-builder 2>/dev/null

# 삭제 확인
npm list -g | grep -E "n8n-mcp|workflow-builder" || echo "글로벌 패키지가 없습니다"

B-4. 로컬 프로젝트에 설치된 경우

특정 프로젝트 폴더에 로컬로 설치했다면, 해당 프로젝트의 node_modules에서 삭제합니다.

# 프로젝트 폴더로 이동
cd /path/to/your/project

# package.json에서 의존성 확인
cat package.json | grep -E "n8n-mcp|workflow-builder"

# 로컬 패키지 삭제
npm uninstall n8n-mcp 2>/dev/null
npm uninstall @n8n/workflow-builder-mcp 2>/dev/null

# node_modules 폴더에서 직접 확인
ls node_modules | grep -E "n8n-mcp|workflow-builder" || echo "로컬 패키지가 없습니다"

Case C | 공통 정리 작업

Docker와 npx 모두 해당되는 공통 정리 작업입니다.

C-1. 환경 변수 및 설정 파일 정리

기존 MCP 서버에서 사용하던 환경 변수나 설정 파일이 있다면 정리합니다. .env 파일, .bashrc, .zshrc 등에서 더 이상 사용하지 않는 변수를 제거하거나 주석 처리합니다.

# .env 파일에서 기존 설정 확인 및 정리
# 불필요한 변수 예시 (제거 대상)
# OLD_N8N_MCP_API_KEY=...
# N8N_WORKFLOW_BUILDER_URL=...

# 쉘 설정 파일에서 환경 변수 확인
grep -E "N8N_MCP|WORKFLOW_BUILDER" ~/.bashrc ~/.zshrc 2>/dev/null

C-2. 삭제 완료 확인

모든 정리가 완료되었는지 확인합니다.

#!/bin/bash
# 정리 상태 확인 스크립트

echo "=== Docker 컨테이너 확인 ==="
docker ps -a | grep -E "n8n-mcp|n8n-workflow-builder" || echo "[v] Docker 컨테이너 없음"

echo ""
echo "=== Docker 이미지 확인 ==="
docker images | grep -E "n8n-mcp|n8n-workflow-builder" || echo "[v] Docker 이미지 없음 또는 새 버전만 있음"

echo ""
echo "=== npx 캐시 확인 ==="
ls ~/.npm/_npx 2>/dev/null && echo "[!] npx 캐시가 남아있음" || echo "[v] npx 캐시 없음"

echo ""
echo "=== 글로벌 npm 패키지 확인 ==="
npm list -g 2>/dev/null | grep -E "n8n-mcp|workflow-builder" || echo "[v] 글로벌 패키지 없음"

echo ""
echo "=== 정리 완료 ==="
echo "이제 czlonkowski/n8n-mcp (Full 버전)를 새로 설치할 준비가 되었습니다."

위 스크립트를 실행하면 기존 MCP 서버가 완전히 정리되었는지 한눈에 확인할 수 있습니다. 모든 항목에서 "[v]"로 표시되면 정리가 완료된 것입니다.

8. 실제 활용 효과

n8n-mcp를 설치하면 Claude와 n8n을 사용하는 방식이 근본적으로 달라집니다. 기존에는 노드 이름을 추측하고, 설정값을 trial & error로 찾아야 했다면, 이제는 Claude가 정확한 정보를 바탕으로 작업을 수행합니다.

기존 방식 (Before)	n8n-mcp 적용 후 (After)
노드 이름 추측 -> 오류 발생 -> 수정 반복	search_nodes("slack") -> 정확한 노드 타입 즉시 확인
설정값 trial & error -> 여러 번 실패	validate_node(config) -> 배포 전 사전 검증
n8n.io 웹사이트에서 템플릿 수동 검색	search_templates -> 2,709개 템플릿 즉시 검색
워크플로우 JSON 수동 작성 및 복사/붙여넣기	Claude가 직접 생성/수정/배포
노드 옵션 문서 찾아보기	get_node_essentials -> 필요한 설정만 빠르게 확인

특히 validate_node와 validate_workflow 기능은 워크플로우를 배포하기 전에 설정 오류를 미리 발견할 수 있어, 디버깅 시간을 크게 줄여줍니다.

9. 문제 해결 및 FAQ

자주 발생하는 문제들

Q: Claude에서 "n8n-mcp 서버에 연결할 수 없습니다" 오류가 발생합니다.

A: n8n-mcp 컨테이너가 실행 중인지 확인합니다. docker ps | grep n8n-mcp 명령으로 상태를 확인하고, 실행 중이 아니라면 docker compose up -d n8n-mcp로 시작합니다. 또한 Claude Desktop 설정 파일의 경로와 JSON 문법이 올바른지 확인합니다.

Q: 노드 검색은 되는데 워크플로우 생성이 안 됩니다.

A: 이는 n8n API 키가 올바르게 설정되지 않았거나, n8n 인스턴스에 접근할 수 없는 경우입니다. .env 파일에 N8N_API_KEY가 올바르게 설정되어 있는지, 그리고 N8N_API_URL이 n8n 컨테이너에 접근 가능한 주소인지 확인합니다. 같은 Docker 네트워크에 있다면 컨테이너 이름(예: n8n-main)을 사용해야 합니다.

Q: n8n-mcp 컨테이너 로그에서 오류를 확인하고 싶습니다.

A: 다음 명령으로 로그를 확인할 수 있습니다.

docker logs n8n-mcp --tail 100 -f

권장 설정 체크리스트

설정이 완료되면 다음 항목들을 확인합니다.

[v] docker-compose.yml에 n8n-mcp 서비스 추가
[v] .env 파일에 N8N_API_KEY 설정
[v] n8n-mcp 컨테이너 실행 중 (docker ps로 확인)
[v] Claude Desktop 설정 파일 업데이트
[v] Claude Desktop 재시작
[v] 테스트 명령 실행 (예: "Slack 노드 검색해줘")

10. 마무리

이 글에서는 Docker 환경에서 czlonkowski/n8n-mcp를 설정하는 방법을 상세히 다루었습니다. 핵심 내용을 요약하면 다음과 같습니다.

첫째, n8n-mcp-skills와 n8n-mcp는 상호 보완적인 관계입니다. skills는 지식과 방법론을, n8n-mcp는 실제 실행 도구를 제공합니다. 둘 다 설정해야 완전한 n8n 자동화 환경이 구성됩니다.
둘째, Docker 환경에서는 docker exec 방식을 권장합니다. 이 방식은 환경 변수를 docker-compose.yml에서 관리하고, API 키를 .env 파일로 분리하여 보안을 강화합니다. Claude 설정 파일도 단 한 줄로 간결해집니다.
셋째, n8n-mcp의 내장 SQLite와 n8n의 PostgreSQL은 완전히 별개입니다. n8n-mcp는 REST API를 통해서만 n8n 데이터에 접근하므로, n8n의 데이터베이스 종류와 관계없이 동일하게 작동합니다.
넷째, 정기적인 이미지 업데이트로 최신 n8n 노드 정보를 유지합니다. docker compose pull n8n-mcp 명령으로 간단히 업데이트할 수 있습니다.

참고 자료

czlonkowski/n8n-mcp GitHub 저장소 - n8n-mcp 공식 저장소
czlonkowski/n8n-skills GitHub 저장소 - n8n-mcp-skills 공식 저장소
n8n-mcp 릴리스 페이지 - 버전별 릴리스 노트
n8n 공식 문서 - n8n 사용 가이드
Model Context Protocol 소개 - MCP 공식 문서

저작자표시 비영리 변경금지 (새창열림)

'AI 활용' 카테고리의 다른 글

openClaw 활용 가이드 (1편) - 설치부터 채널 연결까지 (0)	2026.02.03
[claude] n8n-mcp-skill로 실전 워크플로우 작성해 볼까요? (1)	2026.01.18
n8n 자동화를 위한 Claude Code Agent Skill 활용하기 (0)	2026.01.18
n8n Code 노드에서 정규표현식(Regex)을 알고 씁시다 (0)	2026.01.17
n8n 워크플로우 생성을 위한 Claude Skill 활용하기 - Desktop (0)	2026.01.17

화이트 샌드박스

n8n-mcp-skill을 위한 n8n-mcp 완벽 설정 가이드

Docker 환경에서 Claude Desktop이 n8n 전문가가 되는 방법

목 차

1. n8n-mcp란 무엇인가 | czlonkowski/n8n-mcp

2. n8n-mcp-skills와 n8n-mcp의 관계

3. MCP 아키텍처 이해하기

4. Docker 실행 방식 비교: docker run vs docker exec

docker run 방식 | 매번 새 컨테이너 생성

docker exec 방식 | 기존 컨테이너 사용 - 권장

두 방식 비교표

원격 Docker 환경 연결 | SSH 방식

원격 환경 구성도

SSH 키 인증 설정 (필수)

Claude Desktop 설정 (원격 SSH 방식)

연결 테스트

세 가지 방식 비교

5. 단계별 설치 가이드

Step 1 | docker-compose.yml에 n8n-mcp 서비스 추가

Step 2 | .env 파일에 API 키 추가

Step 3 | n8n에서 API 키 생성

Step 4 | 컨테이너 시작

Step 5 | Claude Desktop 설정 업데이트

Step 6 | Claude Desktop 재시작

6. 내장 SQLite와 n8n PostgreSQL의 차이

n8n-mcp 업데이트 방법

7. 기존 MCP 서버 정리 및 통합

기존 n8n-mcp 및 n8n-workflow-builder 삭제 방법

Case A | Docker로 설치한 경우

Case B | npx로 로컬에 설치한 경우

Case C | 공통 정리 작업

8. 실제 활용 효과

9. 문제 해결 및 FAQ

자주 발생하는 문제들

권장 설정 체크리스트

10. 마무리

참고 자료

'AI 활용' 카테고리의 다른 글

티스토리툴바

n8n-mcp-skill을 위한 n8n-mcp 완벽 설정 가이드

Docker 환경에서 Claude Desktop이 n8n 전문가가 되는 방법

목 차

1. n8n-mcp란 무엇인가 | czlonkowski/n8n-mcp

2. n8n-mcp-skills와 n8n-mcp의 관계

3. MCP 아키텍처 이해하기

4. Docker 실행 방식 비교: docker run vs docker exec

docker run 방식 | 매번 새 컨테이너 생성

docker exec 방식 | 기존 컨테이너 사용 - 권장

두 방식 비교표

원격 Docker 환경 연결 | SSH 방식

원격 환경 구성도

SSH 키 인증 설정 (필수)

Claude Desktop 설정 (원격 SSH 방식)

연결 테스트

세 가지 방식 비교

5. 단계별 설치 가이드

Step 1 | docker-compose.yml에 n8n-mcp 서비스 추가

Step 2 | .env 파일에 API 키 추가

Step 3 | n8n에서 API 키 생성

Step 4 | 컨테이너 시작

Step 5 | Claude Desktop 설정 업데이트

Step 6 | Claude Desktop 재시작

6. 내장 SQLite와 n8n PostgreSQL의 차이

n8n-mcp 업데이트 방법

7. 기존 MCP 서버 정리 및 통합

기존 n8n-mcp 및 n8n-workflow-builder 삭제 방법

Case A | Docker로 설치한 경우

Case B | npx로 로컬에 설치한 경우

Case C | 공통 정리 작업

8. 실제 활용 효과

9. 문제 해결 및 FAQ

자주 발생하는 문제들

권장 설정 체크리스트

10. 마무리

참고 자료

'AI 활용' 카테고리의 다른 글

관련글

티스토리툴바