Claude 코드로 n8n 워크플로우 구축: n8n-MCP 활용 가이드

AI에게 자동화 워크플로우를 구축하도록 명령하기만 하면 n8n에 준비된 상태로 나타났으면 좋겠다는 생각을 해본 적이 있으신가요? AI 비서가 JSON을 수동으로 복사하거나 노드를 드래그하지 않고도 n8n 워크플로우를 직접 생성, 업데이트 및 실행할 수 있다면 어떨까요? 자연어를 실제 배포 가능한 워크플로우 자동화로 전환하는 시스템인 Claude Code를 활용한 n8n-MCP에 오신 것을 환영합니다.

n8n-MCP란 무엇이며 왜 중요할까요?

n8n-MCP는 Claude Code와 같은 AI 비서를 위한 실행 가능한 도구로 n8n 워크플로우를 노출하는 모델 컨텍스트 프로토콜(Model Context Protocol) 서버입니다. n8n UI 또는 REST API를 통해 워크플로우를 수동으로 실행하는 대신, 자연어로 원하는 것을 설명하면 Claude Code가 올바른 워크플로우를 호출하고 매개변수를 전달하며 결과를 반환합니다.

변화는 미묘하지만 엄청납니다. 전통적인 AI 코딩 비서는 코드를 생성합니다. n8n-MCP를 사용하면 워크플로우를 실행합니다. 웹 검색 워크플로우가 도구가 되고, 데이터 보강 파이프라인이 도구가 되며, Slack 알림 흐름이 도구가 됩니다. Claude Code는 단순히 코드를 생성하는 것이 아니라 실제 시스템을 조율하는 에이전트가 됩니다.

내부 도구를 구축하거나 연구를 자동화하는 개발자에게 이는 다음을 의미합니다.

fetch 호출을 작성할 필요 없이 라이브 API를 쿼리할 수 있습니다.
편집기에서 데이터 파이프라인을 트리거할 수 있습니다.
코드를 커밋하기 전에 외부 데이터를 검증할 수 있습니다.
자신의 스택에 맞춰 사용자 정의 에이전트를 구축할 수 있습니다.

프로토콜은 간단합니다. n8n-MCP는 Claude Code의 도구 호출을 n8n 웹훅 노드에 대한 HTTP 요청으로 변환한 다음, 응답을 Claude에게 다시 마샬링합니다. CLI 워크플로우 내에서 n8n의 400개 이상의 통합 기능을 모두 활용할 수 있습니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

최고의 생산성으로 개발자 팀이 협력할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 귀하의 모든 요구 사항을 충족하며, 훨씬 저렴한 가격으로 Postman을 대체합니다!

button

단계 1: n8n 설치 및 웹 검색 워크플로우 생성

먼저 실행 중인 n8n 인스턴스가 필요합니다. 로컬 개발의 경우 Docker가 가장 빠릅니다.

# n8n 데이터를 위한 디렉토리 생성
mkdir ~/n8n-data && cd ~/n8n-data

# Docker로 n8n 시작
docker run -d --name n8n \
  -p 5678:5678 \
  -v $(pwd):/home/node/.n8n \
  --restart unless-stopped \
  docker.n8n.io/n8nio/n8n

http://localhost:5678을 열고 설정을 완료하세요. 관리자 계정을 생성합니다.

웹 검색 워크플로우 구축

새 워크플로우(New Workflow)를 클릭합니다.
웹훅(Webhook) 노드(트리거)를 추가합니다.

HTTP 메서드: POST
경로: web-search
응답 모드: 마지막 노드가 완료되면(When Last Node Finishes)

3. HTTP 요청(HTTP Request) 노드를 추가합니다.

URL: https://duckduckgo.com/html/?q={{ $json.query }}
메서드: GET

4. HTML 추출(HTML Extract) 노드를 추가합니다.

데이터 속성: data
추출 값:
키: results
CSS 선택자: .result__a
반환 값: Text

5. 출력 형식을 지정하기 위한 설정(Set) 노드를 추가합니다.

설정할 값:
results: {{ $json.results }}

6. 웹훅 → HTTP → HTML 추출 → 설정 순으로 연결합니다.

7. 워크플로우를 활성화합니다(오른쪽 상단의 토글).

수동으로 테스트합니다.

curl -X POST http://localhost:5678/webhook/web-search \
  -H "Content-Type: application/json" \
  -d '{"query":"2026년 인기 AI 주제"}'

검색 결과의 JSON 배열이 표시될 것입니다. 이 워크플로우는 이제 MCP 노출을 위한 준비가 완료되었습니다.

단계 2: n8n-MCP 설치 및 구성

n8n MCP 서버는 n8n과 Claude Code를 연결합니다. 전역적으로 또는 프로젝트 디렉토리에 설치하세요.

# n8n-MCP 저장소 복제
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

# 의존성 설치
npm install

# 프로젝트 빌드
npm run build

환경 변수 구성

n8n-MCP 디렉토리에 .env 파일을 생성합니다.

# .env
N8N_API_URL=http://localhost:5678
N8N_API_KEY=n8n_api_key_여기

n8n UI의 설정 → API(Settings → API)에서 n8n API 키를 얻으세요. API 키 섹션이 보이지 않으면 n8n을 시작할 때 환경 변수를 통해 활성화해야 할 수 있습니다.

# API를 활성화하여 n8n 중지 및 다시 시작
docker stop n8n
docker rm n8n

docker run -d --name n8n \
  -p 5678:5678 \
  -v $(pwd):/home/node/.n8n \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=yourpassword \
  --restart unless-stopped \
  docker.n8n.io/n8nio/n8n

이제 UI에서 API 키를 생성합니다.

MCP 서버 시작

# MCP 서버 시작
npm start

기본적으로 http://localhost:3001에서 실행됩니다. 다음이 표시되어야 합니다.

n8n MCP Server running on http://localhost:3001
Available tools: [ 'web-search' ]

서버는 웹훅 경로가 있는 워크플로우를 자동으로 검색하여 도구로 노출합니다.

단계 3: Claude Code가 n8n-MCP를 사용하도록 구성

Claude Code는 구성 파일을 사용하여 MCP 도구를 검색합니다. Claude Code 구성을 생성하거나 편집합니다.

# Claude Code 구성 디렉토리 찾기
# macOS: ~/Library/Application Support/Claude Code
# Linux: ~/.config/Claude Code
# Windows: %APPDATA%/Claude Code

cd ~/Library/Application\ Support/Claude Code

mcp.json이라는 파일을 생성합니다.

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/n8n-mcp/dist/index.js"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "당신의_n8n_api_key"
      }
    }
  }
}

중요: args에는 절대 경로를 사용하십시오. Claude Code가 프로세스를 생성할 때 상대 경로는 실패합니다.

연결 확인

프로젝트에서 Claude Code를 시작합니다.

claude

로딩되면 다음을 입력합니다.

/list-tools

다음이 표시되어야 합니다.

사용 가능한 도구:
- n8n:web-search (웹 검색 워크플로우를 실행합니다)

도구가 나타나지 않으면 로그를 확인하십시오.

# 다른 터미널에서 Claude Code 로그를 확인합니다.
tail -f ~/Library/Application\ Support/Claude\ Code/logs/mcp.log

일반적인 문제:

ENOENT: n8n-mcp/dist/index.js 경로가 잘못되었습니다.
ECONNREFUSED: n8n이 localhost:5678에서 실행되고 있지 않습니다.
401: N8N_API_KEY가 올바르지 않습니다.

단계 4: 실제 적용 — Claude Code에서 웹 검색

이제 마법이 일어납니다. 어떤 프로젝트 디렉토리에서든 Claude Code를 시작하고 다음을 실행합니다.

claude

프롬프트에 다음을 입력합니다.

n8n의 웹 검색 도구를 사용하여 2026년 인기 AI 주제를 찾아보세요.

Claude Code는 다음을 수행합니다.

n8n:web-search 도구를 인식합니다.
사용자의 의도("2026년 인기 AI 주제")를 파싱합니다.
쿼리 매개변수를 추출합니다.
MCP 서버를 호출합니다.
MCP 서버가 n8n 웹훅을 호출합니다.
n8n이 워크플로우를 실행하고 결과를 반환합니다.
MCP가 Claude Code에 JSON을 반환합니다.
Claude Code가 응답을 형식화하고 표시합니다.

예시 세션

$ claude
> n8n의 웹 검색 도구를 사용하여 2026년 인기 AI 주제를 찾아보세요.

n8n 웹 검색 도구를 사용하여 2026년 인기 AI 주제를 검색하는 데 도움을 드리겠습니다.

n8n:web-search 호출, 쿼리: "2026년 인기 AI 주제"

도구가 8개의 결과를 반환했습니다:
1. "2026년 양자 AI 혁신: 개발자가 알아야 할 사항"
2. "멀티모달 LLM: 텍스트 및 이미지를 넘어서"
3. "에지 AI 배포: 클라우드 비용 40% 절감"
4. "AI 코드 검토 에이전트: 기업에서의 채택 급증"
5. "연합 학습: 개인 정보 보호 우선 AI 훈련"
6. "합성 데이터 생성: 품질 대 수량 논쟁"
7. "AI 환각 탐지: 새로운 오픈 소스 도구"
8. "뉴로모픽 컴퓨팅: 하드웨어-소프트웨어 공동 설계 동향"

이러한 결과를 바탕으로 2026년 주요 인기 AI 주제는 다음과 같습니다:
- 개발자를 위한 양자 AI 통합이 실용화되고 있습니다.
- 멀티모달 모델이 텍스트/이미지를 넘어 오디오/비디오로 확장됩니다.
- 비용 절감을 위한 에지 AI 배포.
- 코드 검토를 위한 AI 에이전트가 기업에서 인기를 얻고 있습니다.
- 개인 정보 보호를 위한 연합 학습.
- 합성 데이터 파이프라인.
- 환각 탐지 도구.
- 뉴로모픽 하드웨어 발전.

한편, n8n UI에서는 워크플로우 실행이 실시간으로 나타나 Claude Code가 원격으로 이를 트리거했음을 증명할 것입니다.

고급 패턴: 에이전트 워크플로우 구축

패턴 1: 여러 소스에서 데이터 보강

GitHub 사용자를 가져온 다음 최근 트윗을 조회하는 워크플로우를 생성합니다.

웹훅 노드(enrich-user)
HTTP 요청 → GitHub API(/users/{{ $json.username }})
HTTP 요청 → X API(/users/by/username/{{ $json.username }})
병합 노드(응답 결합)
설정 노드(최종 객체 형식 지정)

이제 Claude Code에서:

enrich-user 워크플로우를 사용하여 @johndoe의 사용자 프로필을 보강합니다.

Claude는 매개변수를 자동으로 전달하고 구조화된 데이터를 수신합니다.

패턴 2: 조건부 도구 선택

여러 워크플로우를 구축하고 Claude가 선택하도록 합니다.

web-search-duckduckgo: 무료이지만 느립니다.
web-search-serpapi: 유료이지만 구조화되어 있습니다.
web-search-google: 사용자 정의 스크래퍼

프롬프트에서:

Python 비동기 패턴을 검색합니다. 사용 가능한 가장 빠른 웹 검색 도구를 사용하세요.

Claude는 도구 설명을 읽고 사용자의 지시에 따라 선택합니다.

패턴 3: 워크플로우 연결

하나의 워크플로우의 출력이 다른 워크플로우를 트리거할 수 있습니다. 다음을 생성합니다.

fetch-data: 원시 데이터를 가져옵니다.
analyze-data: 데이터를 수락하고 분석을 실행합니다.
summarize-data: 분석을 수락하고 요약을 생성합니다.

Claude Code에서:

판매 데이터를 가져와 Q1 동향을 분석하고 주요 통찰력을 요약합니다.

Claude는 세 가지 워크플로우를 순차적으로 연결하고 그 사이에서 출력을 전달합니다.

웹훅 보안을 잊지 마세요

n8n에 인증 헤더를 추가합니다.

웹훅 노드를 편집합니다.
인증(Authentication)을 헤더 인증(Header Auth)으로 설정합니다.
이름: X-API-Key
값: 당신의-안전한-웹훅-비밀

n8n-MCP의 .env를 업데이트합니다.

N8N_WEBHOOK_SECRET=당신의-안전한-웹훅-비밀

헤더를 전달하도록 MCP 서버를 수정합니다(src/index.ts를 편집해야 합니다).

// 도구 실행 함수에서
const response = await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.N8N_WEBHOOK_SECRET
  },
  body: JSON.stringify(parameters)
});

속도 제한

악용을 방지하기 위해 Redis 캐시 계층을 추가합니다.

// n8n-MCP에서 웹훅 호출 전
import Redis from 'ioredis';
const redis = new Redis();

const rateLimitKey = `rate_limit:${toolName}:${Date.now() / 60000}`;
const count = await redis.incr(rateLimitKey);
if (count > 10) { // 분당 10회 호출
  throw new Error('속도 제한을 초과했습니다');
}
await redis.expire(rateLimitKey, 60);

오류 처리

구조화된 오류를 반환하도록 MCP 서버를 개선합니다.

try {
  const response = await fetch(webhookUrl, {...});
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return await response.json();
} catch (error) {
  return {
    error: error.message,
    status: '실패'
  };
}

Claude Code는 오류를 표시하고 자동으로 다시 시도할 수 있습니다.

결론

n8n-MCP는 n8n을 수동 자동화 도구에서 Claude Code를 위한 프로그래밍 가능한 에이전트 백엔드로 전환합니다. 워크플로우를 시각적으로 구축하고, 도구로 노출하며, 자연어로 복잡한 작업을 조율할 수 있습니다. 설정은 간단합니다. n8n을 설치하고, 웹훅 워크플로우를 생성하고, MCP 서버를 실행하고, Claude Code를 구성하면 됩니다. 그 결과는 사용자의 스택을 이해하고 실제 작업을 실행할 수 있는 맞춤형 AI 에이전트입니다. 그리고 이러한 워크플로우에서 API를 구축할 때, Apidog로 테스트하세요. AI 에이전트도 신뢰할 수 있는 계약이 필요하기 때문입니다.

button