n8n-MCP Docker 연동 가이드: 설정부터 트러블슈팅까지 완벽 정리

1. n8n-MCP란?

n8n-MCP는 n8n 워크플로우 자동화 플랫폼과 AI 모델을 연결해주는 MCP(Model Context Protocol) 서버입니다. 이를 통해 AI 에이전트가 n8n의 800개 이상의 노드 정보에 접근하고, 워크플로우를 생성/수정/검증할 수 있습니다.

주요 기능

• 노드 검색 및 문서화: n8n의 모든 노드 정보 제공
• 워크플로우 관리: AI를 통한 워크플로우 생성, 수정, 삭제
• 검증 시스템: 워크플로우 배포 전 유효성 검사
• 템플릿 제공: 2,700개 이상의 워크플로우 템플릿

2. Docker Compose 기본 설정

2.1 최소 구성

# docker-compose.yml
services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    hostname: n8n-mcp
    container_name: n8n-mcp
    networks: ['demo']
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - MCP_MODE=http
      - LOG_LEVEL=info
      - PORT=3000
      - AUTH_TOKEN=your-secure-token-here  # ← 반드시 변경
      - N8N_API_URL=http://n8n:5678

networks:
  demo:
    driver: bridge

2.2 프로덕션 권장 설정 (100명 동시 사용자 기준)

# docker-compose.yml
services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    hostname: n8n-mcp
    container_name: n8n-mcp
    networks: ['demo']
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # 기본 설정
      - MCP_MODE=http
      - N8N_MODE=true                        # ← n8n 호환성 개선
      - LOG_LEVEL=warn                       # ← 프로덕션에서는 warn 권장
      - PORT=3000
      - AUTH_TOKEN=${MCP_AUTH_TOKEN}         # ← 환경변수로 관리
      - N8N_API_URL=http://n8n:5678

      # 세션 관리
      - N8N_MCP_MAX_SESSIONS=200             # ← 동시 세션 수
      - SESSION_TIMEOUT_MINUTES=15           # ← 비활성 세션 정리

      # Rate Limit (올바른 변수명 사용!)
      - AUTH_RATE_LIMIT_WINDOW=60000         # ← 1분 (밀리초)
      - AUTH_RATE_LIMIT_MAX=50               # ← IP당 분당 50 요청

      # 텔레메트리 비활성화
      - N8N_MCP_TELEMETRY_DISABLED=true      # ← 올바른 변수명

    # 리소스 제한
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 256M

networks:
  demo:
    driver: bridge

2.3 보안 토큰 생성

# 32자 이상의 강력한 토큰 생성
openssl rand -base64 32
# 출력 예: K7xR2mN9pQ4wL1vB8cY6tH3jF0sA5uE7

# .env 파일에 저장
echo "MCP_AUTH_TOKEN=$(openssl rand -base64 32)" >> .env

3. 환경변수 완벽 가이드

3.1 자주 틀리는 환경변수 ⚠️

많은 사용자가 환경변수 이름을 잘못 사용합니다. 아래 표를 참고하세요:

3.2 전체 환경변수 목록

# 필수 설정
- MCP_MODE=http                    # 서버 모드 (http/stdio)
- PORT=3000                        # 서버 포트
- AUTH_TOKEN=your-token            # 인증 토큰 (32자 이상 권장)

# n8n 연결
- N8N_API_URL=http://n8n:5678      # n8n API URL
- N8N_MODE=true                    # n8n 호환성 모드

# 세션 관리
- N8N_MCP_MAX_SESSIONS=100         # 최대 동시 세션 (기본: 100)
- SESSION_TIMEOUT_MINUTES=5        # 세션 타임아웃 (기본: 5분)

# Rate Limit
- AUTH_RATE_LIMIT_WINDOW=900000    # 윈도우 크기 (기본: 15분)
- AUTH_RATE_LIMIT_MAX=20           # 최대 요청 수 (기본: 20)

# 멀티테넌트 (선택)
- ENABLE_MULTI_TENANT=true         # 멀티테넌트 활성화
- MULTI_TENANT_SESSION_STRATEGY=instance  # 세션 전략

# 텔레메트리
- N8N_MCP_TELEMETRY_DISABLED=true  # 텔레메트리 비활성화
# 또는
- TELEMETRY_DISABLED=true
# 또는
- DISABLE_TELEMETRY=true

# 로깅
- LOG_LEVEL=info                   # debug/info/warn/error

# 보안
- NODE_ENV=production              # 프로덕션 모드
- TRUST_PROXY=1                    # 리버스 프록시 뒤에서 사용 시

3.3 코드에서 환경변수가 정의된 위치

각 환경변수가 코드 어디에서 사용되는지 알아두면 디버깅에 도움됩니다:

// 📁 src/telemetry/config-manager.ts (257-285번 라인)
// 텔레메트리 비활성화 환경변수 체크
private isDisabledByEnvironment(): boolean {
  const envVars = [
    'N8N_MCP_TELEMETRY_DISABLED',
    'TELEMETRY_DISABLED',
    'DISABLE_TELEMETRY'
  ];
  // ...
}

// 📁 src/http-server-single-session.ts (1105-1107번 라인)
// Rate limit 설정
const authLimiter = rateLimit({
  windowMs: parseInt(process.env.AUTH_RATE_LIMIT_WINDOW || '900000'),
  max: parseInt(process.env.AUTH_RATE_LIMIT_MAX || '20'),
});

// 📁 src/http-server-single-session.ts (45번 라인)
// 최대 세션 수
const MAX_SESSIONS = Math.max(1, parseInt(
  process.env.N8N_MCP_MAX_SESSIONS || '100', 10
));

// 📁 src/http-server-single-session.ts (113-115번 라인)
// 세션 타임아웃
private sessionTimeout = parseInt(
  process.env.SESSION_TIMEOUT_MINUTES || '5', 10
) * 60 * 1000;

4. n8n MCP Client 노드 설정

4.1 Credential 생성

1. n8n에서 Settings → Credentials → Add Credential
2. MCP Client API 선택
3. 설정 입력:

4.2 Transport 선택 주의사항

⚠️ 중요: SSE가 아닌 "Streamable HTTP"를 선택하세요!

Transport 옵션:
├── ✅ Streamable HTTP (권장)
└── ❌ SSE (deprecated) - 연결 루프 발생 가능

4.3 워크플로우 예시

{
  "nodes": [
    {
      "name": "Chat Trigger",
      "type": "n8n-nodes-base.chatTrigger",
      "position": [250, 300]
    },
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "position": [450, 300],
      "parameters": {
        "options": {}
      }
    },
    {
      "name": "MCP Client",
      "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
      "position": [450, 500],
      "parameters": {
        "operation": "executeTool"
      }
    }
  ],
  "connections": {
    "Chat Trigger": {
      "main": [[{"node": "AI Agent", "type": "main", "index": 0}]]
    },
    "MCP Client": {
      "ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]]
    }
  }
}

5. 트러블슈팅 가이드

5.1 SSE 연결 루프 문제

증상:

n8n-mcp  | [INFO] GET /mcp
n8n-mcp  | [INFO] SSE stream request received - establishing SSE connection
n8n-mcp  | [INFO] Closing previous session for SSE
n8n-mcp  | [INFO] Creating new N8NDocumentationMCPServer for SSE...
# 위 로그가 무한 반복

원인:

• n8n MCP Client가 HTTP Streamable이 아닌 SSE로 연결 시도
• SSE POST 메시지 핸들러 미구현으로 인한 연결 실패 후 재시도

해결 방법:

# 1. N8N_MODE 환경변수 추가
environment:
  - N8N_MODE=true  # ← 추가

# 2. n8n에서 MCP Client credential 재설정
#    Transport: "Streamable HTTP" 선택 확인

# 3. 컨테이너 재시작
docker compose down n8n-mcp && docker compose up -d n8n-mcp

5.2 HTTP 406 Not Acceptable 에러

증상:

Error in sub-node 'MCP Client' Could not connect to your MCP server
HTTP 406 Not Acceptable

원인:

• n8n 버전 1.104.1 이전: HTTP Streamable 미지원
• Content negotiation 실패

해결 방법:

# n8n 버전 확인
docker exec n8n n8n --version

# n8n 버전 업그레이드 (1.104.1 이상 필요)
# docker-compose.yml에서:
services:
  n8n:
    image: n8nio/n8n:latest  # 최신 버전 사용

5.3 인증 실패 (401 Unauthorized)

증상:

Authentication failed: Invalid token

체크리스트:

# 1. AUTH_TOKEN 확인
docker exec n8n-mcp env | grep AUTH_TOKEN

# 2. n8n credential의 토큰과 일치하는지 확인

# 3. Bearer 형식 확인 (n8n credential 설정)
#    올바른 형식: Bearer your-token
#    잘못된 형식: your-token (Bearer 누락)

# 4. 토큰 앞뒤 공백 확인
echo "AUTH_TOKEN='${AUTH_TOKEN}'" | cat -A

5.4 연결 테스트

# Health check
curl http://localhost:3000/health

# 응답 예시:
{
  "status": "ok",
  "mode": "sdk-pattern-transports",
  "version": "2.33.5",
  "sessions": {
    "active": 0,
    "total": 0,
    "max": 200
  }
}

# MCP 엔드포인트 정보
curl http://localhost:3000/mcp

# Docker 내부 네트워크 테스트
docker exec n8n-mcp wget -qO- http://n8n:5678/healthz

5.5 메모리 누수 의심 시

# 현재 메모리 사용량 확인
curl http://localhost:3000/health | jq '.memory'

# 세션 상태 확인
curl http://localhost:3000/health | jq '.sessions'

# 세션이 계속 증가하면 타임아웃 조정
environment:
  - SESSION_TIMEOUT_MINUTES=5  # 더 짧게 설정

6. 아키텍처 패턴

6.1 단일 사용자 (개발/테스트)

[User] → [n8n-mcp:3000] → [n8n:5678]

# 최소 설정
environment:
  - MCP_MODE=http
  - AUTH_TOKEN=dev-token
  - N8N_API_URL=http://n8n:5678

6.2 다중 사용자 (100명 이하)

[Users] → [n8n-mcp:3000] → [n8n:5678] → [DB]
              ↓
         [MAX_SESSIONS=200]

# 다중 사용자 설정
environment:
  - N8N_MCP_MAX_SESSIONS=200
  - SESSION_TIMEOUT_MINUTES=15
  - AUTH_RATE_LIMIT_MAX=50

6.3 대규모 (Queue Mode + Workers)

                    ┌─→ [n8n-worker-1]
[Users] → [LB] → [n8n-mcp] → [n8n] ─┼─→ [n8n-worker-2] → [Redis/DB]
          (sticky)              └─→ [n8n-worker-3]

# n8n Queue Mode 설정
services:
  n8n:
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis

  n8n-worker:
    image: n8nio/n8n
    command: worker
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
    deploy:
      replicas: 3

7. 모니터링 설정

7.1 Health Check 활용

services:
  n8n-mcp:
    # ... 기존 설정
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

7.2 로그 수집 (선택사항)

services:
  n8n-mcp:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

7.3 Prometheus 메트릭 (향후 지원 예정)

# 현재는 health 엔드포인트로 기본 메트릭 확인
curl http://localhost:3000/health | jq '{
  sessions: .sessions.active,
  memory_mb: .memory.used,
  uptime: .uptime
}'

8. FAQ

Q: SSE와 HTTP Streamable의 차이점은?

A:

• SSE (Server-Sent Events): 단방향 스트리밍, deprecated
• HTTP Streamable: 양방향 통신, n8n 1.104.1+ 지원, 권장 방식

Q: AUTH_TOKEN은 얼마나 길어야 하나요?

A: 최소 32자 이상을 권장합니다. 짧은 토큰은 경고가 표시됩니다:

# 권장 방법
openssl rand -base64 32

Q: 동시 사용자가 많으면 어떻게 확장하나요?

A:

1. 100명 이하: 단일 인스턴스, N8N_MCP_MAX_SESSIONS=200
2. 100-500명: 메모리 2G, N8N_MCP_MAX_SESSIONS=600
3. 500명 이상: 로드밸런서 + 다중 인스턴스 (sticky session 필수)

Q: 텔레메트리는 어떤 데이터를 수집하나요?

A: 익명화된 사용 통계만 수집합니다:

• 사용된 MCP 도구 (파라미터 제외)
• 워크플로우 구조 (민감 정보 제거)
• 에러 패턴 (해시 처리)

수집하지 않는 것: URL, API 키, 개인정보, 워크플로우 데이터

Q: n8n Queue Mode와 함께 사용할 수 있나요?

A: 네, n8n-mcp는 n8n의 실행 모드와 독립적으로 동작합니다. Queue Mode의 워크플로우도 정상적으로 MCP 도구를 사용할 수 있습니다.

9. 참고 자료

• n8n-MCP GitHub Repository
• n8n 공식 문서
• MCP Protocol 스펙
• n8n MCP Client 노드 문서

10. 다음 단계

이 가이드를 따라 n8n-MCP를 성공적으로 연동했다면, 다음 주제를 탐색해보세요:

1. AI 에이전트 워크플로우 구축: MCP를 활용한 자동화 워크플로우 설계
2. 커스텀 MCP 도구 개발: n8n-mcp 확장하기
3. 프로덕션 배포: Kubernetes, Docker Swarm 환경 구성

시리즈 목차:

1. n8n-MCP Docker 연동 가이드 ← 현재 글
2. AI 에이전트와 MCP 활용 워크플로우 (예정)
3. n8n-MCP 프로덕션 배포 가이드 (예정)