n8n Claude Code 연동

목차

• 이 방식을 선택해야 하는 이유
• 사전 요구 사항
• Step 1: 디렉토리 구조 생성
• Step 2: Docker Compose 설정
• Step 3: 컨테이너 실행 및 Claude 인증
• Step 4: SSH 연결 설정
• Step 5: n8n SSH Credential 설정
• Step 6: n8n 워크플로우 생성
• Step 7: MCP 서버 설정
• 실전 활용 시나리오
• 주의사항 및 제한
• 자주 묻는 질문

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

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일 실제 구축 경험을 바탕으로 작성되었습니다.