n8n-MCP 연결하기 — Claude Code에 'n8n 손발' 달아 주기

지난 강의에서 본 파이프라인 그림의 맨 아래, n8n 캔버스에 실제로 노드를 그려 넣으려면 Claude Code가 내 n8n에 '손'을 뻗을 수 있어야 합니다. 기본 상태의 Claude Code는 내 n8n 계정이 어디 있는지도, 그 안에 워크플로우를 만들 권한이 있는지도 모릅니다. 그 다리를 놓아 주는 것이 바로 n8n-MCP입니다.

Claude Code 설치와 기본 사용법은 앞선 코스를 참고하세요. 이번 강의는 이미 Claude Code가 깔려 있고 터미널에서 실행된다는 전제로, n8n 전용 세팅에만 집중합니다.

MCP가 뭐길래 — '만능 어댑터'

MCP(Model Context Protocol)는 AI 에이전트와 외부 도구를 이어 주는 '공용 규격'입니다. 나라마다 콘센트 모양이 달라도 만능 여행용 어댑터 하나면 어디서든 충전할 수 있듯이, MCP는 Claude Code라는 플러그를 n8n·구글·슬랙 같은 서로 다른 콘센트에 꽂아 주는 어댑터입니다. n8n-MCP는 그중 'n8n 전용 어댑터'인 셈입니다.

연결이 되면 Claude Code는 다음과 같은 'n8n 전용 도구'들을 손에 쥐게 됩니다. 이 도구들이 있어야 AI가 감으로 찍지 않고 정확한 노드/파라미터로 워크플로우를 만듭니다.

• 노드 문서 조회: 특정 노드가 어떤 설정을 받는지 정확히 읽어 옵니다(추측 방지).
• 노드 목록 나열: 이 인스턴스에서 쓸 수 있는 노드 전체를 봅니다.
• 노드 검색: 'gmail', 'if', 'schedule'처럼 필요한 기능의 노드를 찾습니다.
• 워크플로우 생성/수정: n8n API로 실제 인스턴스에 워크플로우를 써 넣거나 고칩니다.

준비물: URL과 API 키, 딱 두 가지

다리를 놓으려면 두 개의 비밀값이 필요합니다. (1) 내 n8n이 어디 있는지 알려 주는 인스턴스 API URL, (2) 그 문을 열 열쇠인 API 키입니다.

두 값 준비하기

1. n8n에 로그인해 Settings → n8n API 메뉴로 들어갑니다.
2. 'Create API key'를 눌러 새 키를 발급하고, 딱 한 번만 보이는 그 문자열을 복사해 둡니다.
3. 브라우저 주소창에서 내 n8n 기본 주소를 확인합니다. 클라우드면 https://<워크스페이스>.app.n8n.cloud, 로컬이면 http://localhost:5678 형태입니다.
4. 이 URL 끝에 슬래시(/)가 붙어 있으면 반드시 지웁니다. 예: .cloud/ (X) → .cloud (O).

API 키와 URL은 채팅창에 붙여넣지 마세요. 대화 기록에 비밀값이 남을 수 있습니다. 아래 설정 파일에 직접 적는 방식으로만 전달합니다. 또한 URL 끝의 슬래시 하나 때문에 연결이 실패하는 경우가 흔하니 꼭 확인하세요.

mcp.json 설정하기

프로젝트 폴더에 MCP 설정 파일을 만들고, n8n-MCP 서버를 npx로 실행하도록 적습니다. 두 비밀값은 env 항목에 넣습니다. 아래는 macOS·Linux용 표준 형태입니다.

mcp.json (macOS / Linux)

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://내워크스페이스.app.n8n.cloud",
        "N8N_API_KEY": "여기에_발급받은_API_키"
      }
    }
  }
}

Windows에서 WSL 없이 쓴다면 npx를 바로 부르지 못하는 경우가 있습니다. 이때는 command를 cmd로 바꾸고 /c 로 감싸 줍니다.

mcp.json (Windows, WSL 미사용)

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://내워크스페이스.app.n8n.cloud",
        "N8N_API_KEY": "여기에_발급받은_API_키"
      }
    }
  }
}

손으로 설정하기 번거롭다면 Claude Code에게 직접 설치를 시킬 수도 있습니다. n8n-MCP 서버와 n8n 스킬의 GitHub 저장소 주소 두 개를 알려 주면, 에이전트가 mcp.json 작성과 스킬 설치를 대신 해 줍니다.

Claude Code에게 설치를 맡기는 프롬프트

아래 두 GitHub 저장소를 참고해서 이 프로젝트에 n8n 연동을 설치해줘.
1) n8n-MCP 서버: <n8n-mcp 저장소 URL>
2) n8n 스킬: <n8n 스킬 저장소 URL>

- mcp.json에 n8n-mcp 서버 설정을 추가해줘. (npx 실행, env로 N8N_API_URL / N8N_API_KEY)
- n8n 스킬은 .claude/skills/ 아래에 설치해줘.
- 비밀값 자리는 플레이스홀더로 두고, 내가 직접 채우도록 안내만 해줘.
- 설치가 끝나면 재시작 후 확인하는 방법을 알려줘.

재시작하고 확인하기

설정 파일을 저장했다고 바로 켜지는 게 아닙니다. Claude Code는 시작할 때만 MCP 설정을 읽으므로, 반드시 한 번 껐다 켜야 새 다리가 연결됩니다.

활성화 확인 절차

1. 실행 중인 Claude Code를 완전히 종료합니다(exit).
2. 같은 프로젝트 폴더에서 Claude Code를 다시 실행합니다.
3. /mcp 를 입력해 서버 목록을 봅니다. n8n MCP 옆에 'connected'가 뜨면 다리가 놓인 것입니다.
4. 설치한 스킬 목록도 함께 확인해, n8n 스킬이 인식됐는지 봅니다.

가장 흔한 실수는 '재시작을 안 하는 것'입니다. 설정을 아무리 잘 써도 재시작 전에는 아무 일도 일어나지 않습니다. /mcp에 connected가 안 뜨면 URL 슬래시, API 키 오타, 재시작 여부부터 점검하세요. 참고로 이 세팅은 클라우드 n8n과 셀프호스팅 n8n 모두에서 동일하게 동작합니다.

YOLO 모드 — 매번 승인 누르지 않기

n8n을 지을 때 Claude Code는 노드 검색, 문서 조회, 워크플로우 쓰기 등 도구를 수십 번 호출합니다. 기본값은 호출마다 사용자에게 '허용할까요?'를 묻는데, 빌드 중에는 이게 상당히 번거롭습니다. 권한 승인을 건너뛰는 모드(흔히 YOLO 모드, --dangerously-skip-permissions)를 켜면 매번 확인 없이 쭉 진행합니다.

이름 그대로 '위험을 건너뛰는' 모드입니다. 에이전트가 확인 없이 파일을 수정하거나 인스턴스에 쓰기를 할 수 있으니, 중요한 데이터가 없는 연습용 프로젝트/인스턴스에서만 쓰고, 실 운영 환경에서는 신중히 판단하세요.

연결이 됐는지 확실히 — 스모크 테스트

connected 표시만 믿기보다, 실제로 '쓰기'가 되는지 아주 사소한 워크플로우를 하나 만들어 확인해 보는 걸 권합니다. Claude Code에게 '수동 트리거 + Set 노드' 정도의 hello-world를 만들라고 시키고, n8n 캔버스에 그게 나타나면 파이프의 끝까지 뚫린 것입니다.

이제 다리가 놓였습니다. 하지만 다리만으로는 부족합니다. 에이전트가 '무엇을' 만들지, '어떻게' 잘 만들지를 알려 주는 지식이 필요하죠. 다음 강의에서 Skills·SOP.md·CLAUDE.md라는 지식 3층을 쌓아 올립니다.