naver-flight-mcp
네이버 항공권 검색 API를 사용하여 최저가 항공권 정보를 조회하는 Model Context Protocol (MCP) 서버입니다.
✨ 주요 기능
- 직항 항공권 최저가 검색 (성인 1명, 이코노미 클래스)
- 왕복 항공편 정보 조회 (출발/도착 시간, 소요시간, 항공편명)
- 최저가 순 상위 10개 항공권 정보 제공
- 실시간 SSE 스트림 처리로 완전한 데이터 수집
- 상세한 로그로 검색 과정 추적
🚀 설치 및 설정
1. 프로젝트 클론 및 설치
# 프로젝트 클론
git clone https://github.com/your-username/naver-flight-mcp.git
cd naver-flight-mcp
# 의존성 설치
npm install
# TypeScript 빌드
npm run build
2. Cursor MCP 설정
Windows: C:\Users\{사용자명}\.cursor\mcp.json
MacOS: ~/.cursor/mcp.json
설정 파일 예시
{
"mcpServers": {
"naver-flight": {
"command": "node",
"args": ["C:/Users/{사용자명}/naver-flight-mcp/dist/index.js"],
"env": {}
}
}
}
실제 경로 예시 (Windows)
{
"mcpServers": {
"naver-flight": {
"command": "node",
"args": ["C:/Users/hwang/naver-flight-mcp/dist/index.js"],
"env": {}
}
}
}
3. Cursor 재시작
MCP 설정을 추가한 후 Cursor를 재시작하면 네이버 항공권 검색 도구를 사용할 수 있습니다.
📖 사용 방법
Cursor에서 사용
MCP 설정 후 Cursor에서 다음과 같이 사용할 수 있습니다:
네이버 항공권 검색: 부산(PUS) → 나리타(NRT), 2025-12-15 ~ 2025-12-19
검색 파라미터
{
departure: "PUS", // 출발지 공항 코드
arrival: "NRT", // 도착지 공항 코드
departureDate: "2025-12-15", // 출발일 (YYYY-MM-DD)
returnDate: "2025-12-19" // 복귀일 (YYYY-MM-DD)
}
출력 예시
항공권 검색 결과 (PUS → NRT):
순위: 1
출발일: 20251215
복귀일: 20251219
가는편: 7C1153
오는편: 7C1154
총요금: 278,700원
가는편 출발: 11:05
가는편 도착: 13:10
소요시간: 125분
오는편 출발: 14:05
오는편 도착: 16:45
소요시간: 160분
---
🧪 테스트 결과
2025년 12월 부산(PUS) - 나리타(NRT) 검색 결과
| 날짜 | 최저가 | 항공편 | 상태 |
|---|---|---|---|
| 2025-12-01 ~ 2025-12-05 | 304,000원 | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-08 ~ 2025-12-12 | 277,000원 | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-15 ~ 2025-12-19 | 278,700원 | 7C1153/7C1154 | ✅ 성공 |
| 2025-12-22 ~ 2025-12-26 | 416,400원 | 7C1153/7C1154 | ✅ 성공 |
인천(ICN) - 나리타(NRT) 검색 결과
| 날짜 | 최저가 | 항공편 | 상태 |
|---|---|---|---|
| 2025-12-15 ~ 2025-12-19 | 312,600원 | BX0164/BX0163 | ✅ 성공 |
🔧 기술적 특징
SSE 스트림 처리 개선
- 실시간 데이터 수집: 네이버 API의 Server-Sent Events를 완전히 처리
- 점진적 데이터 증가: 0개 → 16개 → 18개 → 20개 → 76개 → 77개
- 최종 유효 데이터 선택: 가장 많은 데이터가 포함된 응답 사용
- 상세한 로그: 각 단계별 데이터 수집 과정 추적
로그 예시
SSE 응답 처리 시작...
SSE 데이터 수신: 항공편 0개, 요금 0개
SSE 데이터 수신: 항공편 16개, 요금 32개
유효한 데이터 발견: 항공편 16개, 요금 32개
SSE 데이터 수신: 항공편 20개, 요금 100개
유효한 데이터 발견: 항공편 20개, 요금 100개
최종 데이터: 항공편 20개, 요금 100개
총 7009개의 요금 정보 발견
처리 완료 - 10개의 유효한 항공편
📁 프로젝트 구조
naver-flight-mcp/
├── src/
│ ├── tools/
│ │ └── NaverFlightSearch.ts # 네이버 항공권 검색 도구
│ └── index.ts # MCP 서버 진입점
├── dist/ # 빌드된 파일
├── NAVER_FLIGHT_API_ANALYSIS.md # API 분석 문서
├── NAVER_FLIGHT_MCP_TEST_RESULTS.md # 테스트 결과
├── package.json
├── tsconfig.json
└── README.md
🔌 API 정보
- 엔드포인트:
https://flight-api.naver.com/flight/international/searchFlights - 방식: REST API (Server-Sent Events)
- 검색 조건: 성인 1명, 직항만, 이코노미 클래스 (고정)
- 응답 시간: 일반적으로 4-5초 소요
🛠️ 개발자 정보
로컬 개발
# 개발 서버 실행
npm run dev
# 빌드
npm run build
# 로그 확인
node dist/index.js
의존성
- TypeScript: 타입 안전성
- node-fetch: HTTP 요청 처리
- zod: 스키마 검증
- @modelcontextprotocol/sdk: MCP 서버 구현
📄 라이선스
MIT