SDK .kr
Login
모든글
n8n Claude Code 연동
S

Lv.1 SDK

2026년 1월 22일 오후 11:46

조회 1 공감 0

n8n Claude Code 연동은 복잡한 AI 자동화 워크플로우를 단일 노드로 단순화하고, API 종량제 비용 대신 월정액 구독 내에서 AI 기능을 활용할 수 있게 해주는 방법입니다. Docker 컨테이너로 Claude Code를 설치하고 SSH 노드로 연결하면, PDF 분석, 이미지 인식, 데이터 처리 등 다양한 AI 작업을 예측 가능한 고정 비용으로 실행할 수 있습니다. 이 글에서는 실제 구축 과정을 단계별로 안내합니다.



목차



이 방식을 선택해야 하는 이유

n8n을 사용해 자동화 워크플로우를 구축해본 분들이라면, AI 기능을 추가할 때마다 API 비용이 누적되는 고민을 해보셨을 겁니다. PDF 분석, 이미지 인식, 데이터 처리 등 AI가 필요한 작업마다 API 호출 비용이 발생하고, 이는 자동화의 가장 큰 걸림돌이 됩니다.

하지만 Claude Code를 Docker 컨테이너로 n8n에 연동하면, 월 구독료($20~$200) 내에서 사실상 무제한으로 AI 자동화를 실행할 수 있습니다.


비용 구조의 변화

기존 API 방식은 사용량에 따라 비용이 증가하고, 토큰당 과금으로 예측 불가능한 청구서가 발생합니다. 반면 Docker와 구독을 활용한 새로운 방식은 월 고정 비용($20~$200)으로 구독 한도 내에서 무제한 사용이 가능하며, 예측 가능한 비용 관리가 됩니다.


워크플로우 단순화

기존에 PDF 분석을 위해 필요했던 복잡한 노드 구성이 있었습니다.

Trigger - HTTP Request - Code 파싱 - AI 노드 - Code 후처리 - DB 노드

Claude Code 연동 후에는 이렇게 바뀝니다.

Trigger - SSH Claude Code - 결과 처리

단일 노드로 파일 분석, 데이터 추출, DB 업데이트까지 한 번에 처리할 수 있습니다.


MCP 통합의 장점

Claude Code는 MCP(Model Context Protocol) 서버를 통해 외부 서비스와 네이티브로 연동됩니다.

  • Notion - 데이터베이스 직접 조작
  • GitHub - 저장소 관리, PR 생성
  • PostgreSQL/Supabase - DB 쿼리 실행
  • Filesystem - 로컬 파일 읽기/쓰기

n8n에서 별도의 노드 없이, Claude Code 하나로 모든 서비스에 접근할 수 있습니다.



사전 요구 사항

이 가이드를 따라하기 위해서는 다음이 필요합니다.

  • Docker 및 Docker Compose가 설치된 서버
  • n8n Docker 환경 (이미 운영 중이라면 OK)
  • Claude Pro ($20/월) 또는 Max ($100~$200/월) 구독
  • SSH 접근 가능한 환경


Step 1: 디렉토리 구조 생성

먼저 Claude Code와 n8n이 공유할 디렉토리를 생성합니다.


# 공유 디렉토리 생성
mkdir -p /data/workspace
mkdir -p /data/claude-home
mkdir -p /data/claude-npm


권한 설정


chmod 777 /data/workspace


디렉토리 역할

  • /data/workspace - n8n에서 저장한 파일을 Claude가 읽고, Claude가 생성한 파일을 n8n이 읽는 공유 폴더
  • /data/claude-home - Claude 인증 토큰 및 설정 파일 저장
  • /data/claude-npm - npm 패키지 캐시로 컨테이너 재시작 시 빠른 초기화


Step 2: Docker Compose 설정

기존 n8n docker-compose.yml에 Claude Code 서비스를 추가합니다.


version: '3.8'


services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: 172.17.0.1
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: postgres
      DB_POSTGRESDB_PASSWORD: your_password
      N8N_PORT: 5678
      GENERIC_TIMEZONE: Asia/Seoul
      TZ: Asia/Seoul
    volumes:
      - /data/n8n:/home/node/.n8n
      - /var/run/docker.sock:/var/run/docker.sock
      - /data/workspace:/workspace
    network_mode: bridge


  claude-code:
    image: node:20-slim
    container_name: claude-code
    restart: unless-stopped
    stdin_open: true
    tty: true
    environment:
      - TZ=Asia/Seoul
      - HOME=/root
    volumes:
      - /data/workspace:/workspace
      - /data/claude-home:/root/.claude
      - /data/claude-npm:/root/.npm
    working_dir: /workspace
    entrypoint: /bin/sh
    command:
      - -c
      - |
        echo "Installing Claude Code CLI..."
        npm install -g @anthropic-ai/claude-code
        echo "Claude Code installed. Container ready."
        tail -f /dev/null
    network_mode: bridge


핵심 포인트

  • /data/workspace:/workspace - n8n과 Claude Code가 동일한 폴더를 공유
  • /data/claude-home:/root/.claude - 컨테이너 재시작 후에도 인증 유지
  • tail -f /dev/null - 컨테이너가 종료되지 않고 계속 실행


Step 3: 컨테이너 실행 및 Claude 인증

Docker Compose로 컨테이너를 실행합니다.


# 컨테이너 시작
cd /opt/n8n
docker compose up -d


Claude Code 설치 완료 대기 (약 1-2분)


docker logs -f claude-code

"Claude Code installed. Container ready." 메시지가 나타나면 Ctrl+C로 로그 확인을 종료합니다.


Claude 인증 (최초 1회)


docker exec -it claude-code claude auth login

터미널에 URL이 표시됩니다.

Please visit: https://claude.com/code/auth?code=XXXXX

  1. URL을 복사하여 브라우저에서 열기
  2. Claude Pro/Max 계정으로 로그인
  3. 인증 완료 후 터미널에서 확인

인증 확인


docker exec claude-code claude -p "Hello" --print
# 출력: Hello! How can I help you today?


Step 4: SSH 연결 설정

n8n 컨테이너에서 호스트를 통해 Claude Code 컨테이너를 호출합니다.

SSH 키 생성 (없는 경우)


# SSH 키 생성
ssh-keygen -t rsa -b 4096 -f /root/.ssh/n8n_key -N ""


authorized_keys에 추가


cat /root/.ssh/n8n_key.pub >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys


연결 테스트


ssh -i /root/.ssh/n8n_key [email protected] \
  "docker exec claude-code claude -p 'Hello' --print"

Hello! How can I help you today? 메시지가 출력되면 성공입니다.



Step 5: n8n SSH Credential 설정

n8n 웹 UI에서 SSH Credential을 생성합니다.

  1. Settings - Credentials - Add Credential
  2. SSH 선택
  3. 설정값 입력
  • Credential Name - Claude-Host-SSH
  • Host - 172.17.0.1
  • Port - 22
  • Username - root
  • Authentication - Private Key
  • Private Key - /root/.ssh/n8n_key 파일 내용 전체 복사


Step 6: n8n 워크플로우 생성

기본 워크플로우 구조는 다음과 같습니다.

Manual Trigger - Code 프롬프트 준비 - SSH Claude Code 실행


Code 노드 설정


return {
  prompt: "Hello! 오늘 날짜와 시간을 알려줘",
  sessionId: Date.now().toString(36) + Math.random().toString(36).substr(2)
};

주의: n8n의 Code 노드에서는 require('crypto')가 차단되어 있으므로, 위와 같은 방식으로 고유 ID를 생성합니다.


SSH 노드 설정

  • Operation - Execute Command
  • Command - docker exec claude-code claude -p "{{ $json.prompt }}" --print
  • Credential - Claude-Host-SSH

실행 결과 예시


{
  "code": 0,
  "signal": null,
  "stdout": "현재 시간은 14시 06분 44초 (KST, 한국 표준시)입니다.",
  "stderr": ""
}


Step 7: MCP 서버 설정

Claude Code의 기능을 확장하는 MCP 서버를 설정합니다. 설정 파일 경로는 /data/claude-home/settings.json입니다.


{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "your-notion-api-key"
      },
      "disabled": true
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
      },
      "disabled": true
    }
  }
}

MCP 활성화 방법

  1. "disabled": true를 "disabled": false로 변경
  2. API 키 또는 토큰 입력
  3. 컨테이너 재시작: docker restart claude-code


실전 활용 시나리오

텔레그램에서 이미지 분석 후 결과 회신

Telegram Trigger - HTTP 이미지 다운로드 - Move Binary /workspace에 저장 - SSH Claude Code로 분석 - Telegram 결과 전송

SSH Command 예시:


docker exec claude-code claude -p \
  "/workspace/image.jpg 이미지를 분석해서 텍스트로 정리해줘" \
  --print

이메일 수신 후 PDF 분석하여 DB 저장

Email Trigger - Move Binary /workspace에 저장 - SSH Claude Code로 분석 및 DB 저장

MCP를 활용한 SSH Command 예시:


docker exec claude-code claude -p \
  "/workspace/document.pdf의 내용을 분석하고, PostgreSQL의 documents 테이블에 저장해" \
  --print

세션 유지 대화

여러 턴에 걸친 대화가 필요한 경우 session-id를 활용합니다.


# 첫 번째 메시지
docker exec claude-code claude -p "프로젝트 분석을 시작해" \
  --session-id "session123" --print


후속 메시지 (같은 session-id 사용)


docker exec claude-code claude -p "이전 분석 결과를 요약해줘" 
  --session-id "session123" --resume --print



주의사항 및 제한

사용량 제한

  • Claude Pro ($20/월) - 기본 사용량 제공
  • Claude Max ($100~$200/월) - 5x~20x 높은 한도
  • 2025년 8월부터 주간 사용량 제한 도입 예정 - 24시간 백그라운드 작업에 제한이 적용될 수 있습니다.

보안 고려사항

root 권한에서는 --dangerously-skip-permissions 옵션을 사용할 수 없습니다. 대신 일반 모드로 실행해야 합니다.


# 일반 모드로 실행
docker exec claude-code claude -p "작업" --print

타임아웃 설정

긴 작업의 경우 n8n SSH 노드의 타임아웃을 조정해야 합니다.

  • 기본값: 60초
  • 권장값: 300초 (5분) 이상


자주 묻는 질문

Q: Claude Pro와 Max 중 어떤 요금제를 선택해야 하나요?

A: 일반적인 자동화 워크플로우라면 Pro($20/월)로 충분합니다. 하루 종일 대량의 작업을 처리하거나 Claude Opus 모델이 필요하다면 Max를 고려하세요.


Q: API 방식과 비교했을 때 실제로 비용이 절감되나요?

A: 사용량에 따라 다릅니다. 하루에 수십 건 이상의 AI 작업을 실행한다면 월정액이 훨씬 유리합니다. 간헐적인 사용이라면 API 종량제가 더 저렴할 수 있습니다.


Q: 컨테이너를 재시작하면 인증이 풀리나요?

A: 아닙니다. /data/claude-home 디렉토리가 볼륨으로 마운트되어 있어 인증 정보가 유지됩니다.


Q: MCP 서버는 반드시 설정해야 하나요?

A: 아닙니다. MCP는 선택사항입니다. 기본적인 텍스트 처리와 파일 분석만 필요하다면 MCP 없이도 충분히 활용할 수 있습니다. Notion이나 GitHub 연동이 필요할 때 추가하면 됩니다.


Q: n8n 컨테이너에서 직접 Claude Code를 실행할 수는 없나요?

A: 가능하지만 권장하지 않습니다. n8n 공식 이미지에는 docker CLI가 포함되어 있지 않고, 커스텀 이미지를 만들면 n8n 업데이트 시마다 재빌드가 필요합니다. SSH 방식이 유지보수 측면에서 더 효율적입니다.



이 글은 2025년 1월 22일 실제 구축 경험을 바탕으로 작성되었습니다.

댓글 (0)

  • 아직 댓글이 없습니다. 첫 댓글을 작성해보세요!

댓글을 작성하려면 이 필요합니다.

SDK 블로그
SDK .kr

개발 일상과 기술 노트. RSS 와 검색 엔진을 통해 발견될 자료들.

© 2026 SDK.kr — 코드 옆에 적어둔 기록들