1. 왜 n8n에 커스텀 검색 도구가 필요한가
n8n을 사용하여 AI 에이전트를 구축하다 보면 한 가지 큰 벽에 부딪히게 됩니다. 바로 ‘한국형 데이터’의 부재입니다. n8n이 기본적으로 제공하는 검색 도구들은 주로 구글이나 빙(Bing) 기반이라, 우리가 자주 찾는 네이버 블로그의 생생한 후기나 네이버 뉴스의 속보를 가져오는 데에는 한계가 있습니다.
만약 내 AI 비서가 네이버와 구글을 동시에 검색해서 정보를 취합해 준다면 어떨까요? 그것도 내가 원하는 방식대로 데이터를 가공해서 말입니다. 개발자가 아니라고 걱정할 필요는 없습니다.
이 글에서는 VS Code의 AI 코딩 기능을 활용하여 파이썬으로 네이버와 구글 검색 기능을 통합한 API 서버를 만들고, 이를 도커(Docker)로 배포하여 n8n의 툴 에이전트(Tool Agent)와 연동하는 전 과정을 다룹니다.
2. 개발 환경 준비, AI와 함께하는 바이브 코딩
가장 먼저 할 일은 코드를 작성할 환경을 꾸미는 것입니다. 마이크로소프트의 VS Code를 설치하고, 클로드(Claude)와 같은 AI 모델을 에이전트 모드로 설정합니다. 이제부터 우리는 직접 코드를 타이핑하는 것이 아니라, AI에게 지시를 내리는 감독관이 됩니다.
프로젝트 폴더를 만들고 .env 파일을 생성합니다. 이곳은 네이버 API의 클라이언트 ID와 시크릿 키, 그리고 구글 커스텀 서치의 API 키와 같은 민감한 정보를 담아두는 역할을 합니다. AI에게 이렇게 지시해 보세요. “파이썬의 dotenv 라이브러리를 사용해서 .env 파일에 있는 환경 변수를 불러오는 기본 구조를 잡아줘.” AI는 순식간에 안전하게 키를 관리하는 코드를 짜줄 것입니다. 이것이 바로 바이브 코딩의 시작입니다.
3. 검색의 핵심 로직: 네이버와 구글을 하나로
이제 검색 기능을 구현할 차례입니다. 우리의 목표는 네이버 블로그, 네이버 뉴스, 그리고 구글 검색 결과를 통일된 형식으로 받아오는 것입니다. AI 에이전트가 데이터를 쉽게 이해하려면 ‘제목’, ‘링크’, ‘요약 설명’이라는 표준화된 포맷이 필요하기 때문입니다.
네이버 개발자 센터에서 발급받은 키를 사용하여 블로그와 뉴스 검색 API를 호출하는 함수를 만듭니다. 이때 중요한 것은 ‘정확도’와 ‘최신순’ 정렬 옵션을 파라미터로 받을 수 있게 설계하는 것입니다. 구글 검색 역시 구글 클라우드 플랫폼에서 발급받은 키와 검색 엔진 ID(CX)를 활용해 구현합니다.
이 단계에서 중요한 팁은 에러 처리입니다. 검색 결과가 없거나 API 호출 횟수가 초과되었을 때 서버가 멈추지 않고 “검색 결과 없음”이라는 메시지를 반환하도록 예외 처리를 꼼꼼하게 해야 합니다. 물론, 이 또한 AI에게 “예외 처리 구문을 추가해 줘”라고 말하면 해결됩니다.
4. FastAPI로 서버 구축, 가볍고 빠른 API 만들기
함수가 준비되었다면 이제 외부에서 접속할 수 있는 서버로 만들 차례입니다. 파이썬의 FastAPI는 이름처럼 빠르고, 자동으로 API 문서(Swagger UI)까지 만들어주는 아주 훌륭한 프레임워크입니다.
POST 요청 방식으로 /search라는 주소(엔드포인트)를 만듭니다. n8n에서 검색어와 검색 유형(네이버 블로그, 뉴스, 구글 등)을 보내면, 이 서버가 대신 검색하고 결과를 JSON 리스트로 돌려주는 구조입니다.
보안을 위해 헤더 인증 방식을 적용하는 것을 잊지 마세요. 아무나 내 API를 쓰게 할 수는 없으니까요. x-api-key 같은 커스텀 헤더를 정의하고, 미리 설정한 비밀키가 일치할 때만 검색이 작동하도록 만듭니다. 서버 실행은 Uvicorn을 사용합니다. 이 모든 과정이 복잡해 보이지만, AI에게 “FastAPI로 껍데기를 씌워줘”라고 하면 단 몇 초 만에 완성된 코드를 볼 수 있습니다.
5. 도커와 Nginx로 배포
내 컴퓨터에서만 돌아가는 서버는 의미가 없습니다. n8n이 클라우드에 있든 로컬에 있든 언제든 접속할 수 있도록 서버를 배포해야 합니다. 여기서 도커(Docker)가 등장합니다. 도커는 내 코드가 어떤 환경에서도 똑같이 실행되도록 포장해 주는 도시락 같은 존재입니다.
Dockerfile과 docker-compose.yml 파일을 작성합니다. 포트는 외부에서 접속할 수 있게 열어두고(예: 8000번), 서버가 재부팅되어도 자동으로 다시 켜지도록 restart: always 옵션을 추가합니다. 또한 로그나 설정 파일이 날아가지 않도록 볼륨(Volume) 매핑도 설정합니다.
그리고 중요한 것이 바로 HTTPS 설정입니다. n8n은 보안상의 이유로 HTTPS가 아닌 일반 HTTP 주소와는 통신을 거부하는 경우가 많습니다. Nginx Proxy Manager를 도커로 같이 띄워서, 내 도메인에 무료 SSL 인증서를 적용합니다. 이렇게 하면 자물쇠가 달린 안전한 주소로 나만의 API 서버가 탄생합니다.
6. n8n 연동, AI 에이전트
n8n으로 돌아와서 우리가 만든 검색 API를 등록할 차례입니다. n8n의 툴 에이전트(Tool Agent) 노드를 열고 ‘Custom Tool’을 선택합니다. 또는 HTTP Request 노드를 도구로 정의할 수도 있습니다.
도구의 이름은 ‘UniversalSearch’, 설명에는 ‘한국의 네이버 블로그, 뉴스 및 구글 검색이 필요할 때 사용하세요’라고 적어줍니다. 이 설명이 매우 중요합니다. AI는 이 설명을 읽고 언제 이 도구를 꺼내 쓸지 스스로 판단하기 때문입니다.
인증(Credential) 설정에는 앞서 만든 헤더 방식의 API 키를 등록합니다. 이제 AI 에이전트에게 “요즘 유행하는 성수동 맛집을 네이버 블로그에서 찾아서 정리해 줘”라고 채팅을 보내보세요. 에이전트가 여러분이 만든 파이썬 서버를 호출하고, 네이버 검색 결과를 가져와서 요약해 주는 검색엔진을 볼 수 있을 것입니다.
마무리
우리는 오늘 VS Code와 AI의 도움을 받아 파이썬 코드를 작성하고, FastAPI로 서버를 구축하며, 도커와 Nginx로 배포하여 n8n과 연동하는 방법을 봤습니다. 이 과정의 핵심은 기술의 습득이 아닙니다. 비전문가도 AI를 활용하면 얼마든지 자신에게 필요한 도구를 직접 만들 수 있다는 자신감을 얻는 것입니다.
네이버 검색은 시작일 뿐입니다. 이 구조를 응용하면 카카오톡 메시지 보내기, 주식 정보 가져오기, 사내 데이터베이스 조회하기 등 n8n의 기능을 무한대로 확장할 수 있습니다. 자기만의 커스텀 도구로 자동화의 수준을 한 단계 더 높여보시기 바랍니다.