Which integrations are available for this server?

Integrates with Naver Search and DataLab APIs to provide web, news, blog, cafe, image, knowledge iN, encyclopedia, and local search, along with search trend analysis and shopping insight tools by category, device, gender, age, and keyword.

How do I use Naver Search MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Naver Search MCP Server search Naver news for AI semiconductor trends this week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Naver Search MCP Server

by neneungyul2

Overview Schema Source Related Servers Discussions Admin

Python

Remote

ne-naver-api-mcp

NAVER API HUB(검색, 데이터랩)를 쓰는 MCP(Model Context Protocol) 서버입니다. 네이버 검색광고 API 키를 추가하면 Data Lab 상대 지수를 절대 검색량으로 역산하는 도구(estimate_search_volume)도 켜집니다. 네이버 웹문서/블로그/카페 검색, 검색어 트렌드, 쇼핑 인사이트와 함께, 도서 제품 브랜드의 검색·쇼핑·언급 추이를 비교하는 분석 도구(brand_compare_trend, brand_mentions)와 엑셀/CSV 내보내기를 제공합니다.

포크 안내: 이 프로젝트는 isnow890/naver-search-mcp(MIT License)를 바탕으로 합니다. 원본(Node/TypeScript)의 HUB 호출 방식, 인증 처리, 쇼핑 분야 코드 데이터(categories.json)를 파이썬으로 옮기고 분석 기능을 추가했습니다. 원본의 저작권 고지와 라이선스는 LICENSE에 그대로 유지됩니다. Node 버전은 태그 node-v1에 남아 있습니다.

도구 (20개)

구분	도구
카테고리	`find_category` — 자연어로 쇼핑 분야 코드 검색
검색	`search_webkr`, `search_blog`, `search_cafearticle`, `search_news`, `search_image`, `search_kin`, `search_encyc`, `search_local`
데이터랩	`datalab_search`(검색어 트렌드), `datalab_shopping_category`, `datalab_shopping_by_device`, `datalab_shopping_by_gender`, `datalab_shopping_by_age`, `datalab_shopping_keywords`, `datalab_shopping_keyword_by_device`, `datalab_shopping_keyword_by_gender`, `datalab_shopping_keyword_by_age`
분석	`brand_compare_trend`, `brand_mentions`

날짜 인자에는 "today"(한국 시간 기준 오늘)를 쓸 수 있습니다.

NAVER API HUB에서 API를 Application에 추가해야 합니다. 검증일(2026-10-21) 기준 확인된 것은 search_webkr, search_blog, search_cafearticle과 데이터랩 전체(검색어 트렌드, 쇼핑 인사이트 8종)입니다. search_news, search_image, search_kin, search_encyc, search_local은 HUB에 경로가 있지만 확인에 쓴 Application에는 추가되어 있지 않아 HTTP 401 요청한 API는 이 Application에서 활성화되어 있지 않습니다가 돌아왔고, 응답 구조는 확인하지 못했습니다. NCP 콘솔 > NAVER API HUB에서 Application에 해당 API를 추가하면 사용할 수 있습니다.

Related MCP server: mcp-server-naver-search

설치

필요한 것: uv (파이썬은 uv가 알아서 준비합니다), NAVER API HUB 키(NCP_APIGW_API_KEY_ID, NCP_APIGW_API_KEY; NCP 콘솔 > NAVER API HUB에서 Application을 만들어 발급).

Claude Code

claude mcp add ne-naver-api -s user ^
  -e NCP_APIGW_API_KEY_ID=발급ID -e NCP_APIGW_API_KEY=발급Key ^
  -e NAVER_EXPORT_DIR=C:\Users\내이름\Documents\naver-exports ^
  -- uvx --from git+https://github.com/neneungyul2/ne-naver-api-mcp ne-naver-api-mcp

(줄 끝 ^는 Windows cmd의 줄 이음입니다. PowerShell은 `, macOS/Linux는 \를 쓰세요.)

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json에 추가한 뒤 앱을 완전히 종료했다가 다시 실행합니다.

{
  "mcpServers": {
    "ne-naver-api": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/neneungyul2/ne-naver-api-mcp", "ne-naver-api-mcp"],
      "env": {
        "NCP_APIGW_API_KEY_ID": "발급ID",
        "NCP_APIGW_API_KEY": "발급Key",
        "NAVER_EXPORT_DIR": "C:\\Users\\내이름\\Documents\\naver-exports"
      }
    }
  }
}

uvx를 찾지 못하면 "command"에 uvx.exe의 전체 경로를 쓰세요. 배포할 때는 주소 끝에 커밋이나 태그를 붙여 버전을 고정하세요(git+https://...ne-naver-api-mcp@<커밋>).

위 GitHub 주소로 설치하는 방법은 이 저장소의 main이 파이썬 버전일 때만 동작합니다. 그 전에는 로컬 폴더로 설치하세요: uvx --from <이 저장소를 받은 폴더> ne-naver-api-mcp.

환경변수

이름	설명	기본값
`NCP_APIGW_API_KEY_ID`, `NCP_APIGW_API_KEY`	NAVER API HUB 키 (필수)	—
`NAVER_SEARCHAD_CUSTOMER_ID`, `NAVER_SEARCHAD_ACCESS_LICENSE`, `NAVER_SEARCHAD_SECRET_KEY`	네이버 검색광고 API 키 (선택). 세 값이 모두 있으면 검색량 도구 2개가 켜지고, 모두 비면 꺼집니다. 일부만 있으면 서버가 시작하지 않습니다	—
`NAVER_EXPORT_DIR`	엑셀/CSV 저장 폴더. 지정을 권장합니다(MCP 클라이언트가 서버를 실행하는 작업 폴더를 알 수 없어서)	`<작업 폴더>/exports`
`NAVER_CACHE_DIR`	API 응답 캐시 폴더	`<홈>/.naver-search-mcp/cache`
`NAVER_CACHE_TTL_HOURS`	캐시 유지 시간(시간)	`24`
`NAVER_TOOLS_ALLOW`	노출할 도구 이름(쉼표 구분, 비우면 전체). 예: `find_category,brand_compare_trend,brand_mentions`	전체

서버는 환경변수를 우선 쓰고, 비어 있는 키는 작업 폴더의 .env(KEY=VALUE 형식)에서 채웁니다. 키가 없으면 서버는 시작하지 않고 stderr에 안내를 남긴 뒤 종료 코드 1로 끝납니다. 네이버 개발자센터(legacy) 키는 지원하지 않습니다.

도서 브랜드 분석

브랜드는 { "name": "그래머인사이드", "aliases": ["그래머 인사이드", "Grammar Inside"] } 형식입니다(별칭은 표기가 갈리는 이름). 모든 결과에는 limitations가 붙습니다.

`brand_compare_trend`

여러 브랜드의 검색어 트렌드(source: "search") 또는 쇼핑 클릭 추이(source: "shopping", category 필요)를 한 척도의 상대 지수로 비교합니다. Data Lab의 지수는 요청마다 최댓값이 100인 상대값이라, 기준 브랜드를 모든 호출에 넣고 합계 비율로 환산합니다.

기준 브랜드를 생략하면 첫 브랜드를 쓰고, 정밀도가 낮은 브랜드가 있으면 중간 규모 브랜드로 기준을 바꿔 한 번만 다시 계산합니다. 기준 브랜드에 데이터가 없으면 첫 묶음에서 가장 큰 브랜드로 바꿉니다.
쇼핑 인사이트는 키워드 그룹당 1개만 받으므로 이름으로 먼저 조회하고, 데이터가 없으면 별칭을 순서대로(최대 2개) 시도합니다.
값은 실제 검색/클릭 횟수가 아니며, 첫 묶음의 최댓값을 100으로 한 척도라 100을 넘을 수 있습니다.

`brand_mentions`

블로그/카페글/웹문서에서 브랜드 언급 글을 최근 순으로 수집(기본 검색어당 100건)해 월별로 집계하고, 함께 언급된 후보 단어와 예시 문장을 돌려줍니다. 최근 언급 경향을 보는 용도입니다.

검색 API에는 기간 필터가 없어 표본이 최근 글에 한정됩니다. 브랜드마다 닿는 과거가 다르므로 결과의 comparableFrom(소스별 비교 가능 시작일)과 월별 행의 partial(부분 집계)을 확인하세요.
카페글과 웹문서는 날짜가 없어 월별 집계에서 제외됩니다(건수와 후보 분석에는 포함).
baselineQuery(예: "중등 영어 문법 교재")를 주면 그 일반 검색 결과에서 흔한 단어(문법, 영어 등)를 후보에서 뺍니다.
후보 단어는 한국어 형태소 분석(kiwipiepy)으로 뽑으며, 조사는 떼어 내고 브랜드 이름과 별칭은 쪼개지지 않게 처리합니다. 후보가 브랜드인지는 직접 판단하세요.

검색량 역산 (검색광고 API, 선택)

네이버 검색광고 API의 키워드도구는 키워드별 **최근 한 달 PC/모바일 검색수(절대값)**를 알려 줍니다. 키(NAVER_SEARCHAD_*)를 설정하면 아래 도구 2개가 추가됩니다(총 22개). 키 발급: 검색광고 > 도구 > API 사용 관리.

`searchad_keyword_volume`

키워드 목록의 월 검색수(PC, 모바일, 합계)와 경쟁정도를 조회합니다. includeRelated: true이면 연관 키워드를 검색수 많은 순으로 함께 돌려줍니다. 검색광고는 띄어쓰기를 구분하지 않아 공백을 제거해 조회하며, 10 미만은 숫자 대신 < 10으로만 알려 주므로 값은 null, lowVolume: true로 표시합니다(totalUpperBound는 가려진 쪽을 9로 본 상한).

`estimate_search_volume`

브랜드별 월별 절대 검색량을 추정합니다.

Data Lab 검색어 트렌드를 일 단위로 받아 한 척도로 맞춥니다(brand_compare_trend와 같은 기준 브랜드 환산). 단위를 섞으면 "요청 최댓값 100"의 기준이 달라지므로 일 단위로 통일합니다.
검색광고의 월 검색수(브랜드의 이름과 별칭 합, 공백만 다른 키워드는 한 번만)를 어제까지 28일의 지수 합에 맞춰 환산 계수 k = 월 검색수 / 최근 28일 지수 합을 구합니다.
모든 날의 지수에 k를 곱해 월로 합산합니다. 일부 날짜만 있는 달은 partial: true이고, 조회 구간이 그 달의 일부만 덮으면(예: 오늘이 속한 달은 어제까지) fullMonth: false입니다. 이 달은 다른 달과 월 합계로 직접 비교하지 마세요.

브랜드마다 k를 따로 구하고, 브랜드 간 k가 2배 넘게 다르면 경고합니다(두 지표의 집계 정의 차이이거나 작은 브랜드의 지수가 거칠다는 신호).
검색광고가 10 미만으로만 알려 주거나 조회되지 않은 브랜드는 다른 브랜드의 공통 k로 추정하고 경고합니다(오차 큼). 쓸 수 있는 브랜드가 하나도 없으면 오류입니다.
종료일은 어제까지 반영됩니다. 호출은 Data Lab 일 단위 트렌드 + 검색광고 호출(키워드 5개당 1회)이며 dryRun/maxCalls/confirm/exportAs는 아래 공통 인자와 같습니다.
추정값은 대략적인 규모로만 쓰세요. 두 서비스의 집계 정의가 다르고 검색광고의 "최근 한 달"이 정확히 어느 구간인지 문서에 명시되어 있지 않습니다. 실제 키로 후보 구간(길이 7~~35일, 달력상 지난달, 끝점을 앞당긴 구간)을 비교한 결과(2026-10-21, 키워드 7개) 끝점은~~ 어제~~일 때 키워드 간~~ k ~~편차가 가장 작았고, 길이는 24~~28일에서 가장 작아(변동계수 0.03, 30일은 0.05) 28일을 썼습니다. 한 시점의 약한 근거이니 tests/live/test_searchad.py로 다시 확인할 수 있습니다. 같은 조건에서 k는 키워드 월 검색수가 2천~22만인 7개 사이에서 최대 1.1배 차이였고, 월 260인 키워드는 지수 반올림이 거칠어 1.3배 벗어났습니다.

공통 인자와 호출 한도

인자	설명
`dryRun`	호출 없이 예상 호출 수(`estimatedCalls`, 비교 트렌드는 최악의 경우 `estimatedCallsMax`)만 계산
`maxCalls`	한 번의 실행에서 쓸 API 호출 상한 (기본 30)
`confirm`	예상 호출 수가 상한을 넘어도 진행
`exportAs`	지정하면 결과를 `<이름>.xlsx`와 시트별 CSV로 저장 (엑셀의 `=`로 시작하는 셀은 수식으로 실행되지 않게 처리, 내보내기가 실패해도 분석 결과는 돌려줌)

NAVER API HUB에는 호출 한도를 조회하는 API나 응답 헤더가 없습니다. 월 사용량(검색 775,000건, 데이터랩 API별 50,000건)은 NCP 콘솔 > NAVER API HUB > Usage Statistics에서 확인하세요. 이 서버는 한 번의 실행 안에서의 호출 수만 세고, 같은 요청은 캐시로 호출을 아낍니다.

개발

uv sync                                   # 의존성 설치
uv run pytest                             # 테스트 (네트워크 없음, 라이브 테스트는 건너뜀)
NAVER_LIVE_TEST=1 uv run pytest tests/live   # 실제 API 확인 (.env의 키 필요, 호출 약 23회)
uv run python scripts/record_fixtures.py  # 테스트 샘플을 실제 응답으로 다시 녹화 (호출 6회)

PowerShell에서는 $env:NAVER_LIVE_TEST=1; uv run pytest tests/live처럼 실행하세요.

로컬 폴더로 설치(uvx --from <폴더> ne-naver-api-mcp)할 때 uv는 빌드 결과를 캐시합니다. 소스를 고치면 다시 빌드하도록 pyproject.toml에 [tool.uv] cache-keys를 설정해 두었습니다. 그래도 이전 코드가 실행되는 것 같으면 uv cache clean ne-naver-api-mcp로 캐시를 비우세요.

구성: src/ne_naver_api_mcp/ — client.py(HUB HTTP 클라이언트), analysis/(환산, 비교 트렌드, 언급 수집, 후보 추출), export.py, cache.py, tools/(MCP 도구 등록), server.py. Node 구현과의 테스트 대응표는 docs/superpowers/parity.md, 설계 문서는 docs/superpowers/specs/에 있습니다.

라이선스

MIT License. 원본 저작권 고지는 LICENSE를 보세요.

Available Tools

20 tools

brand_compare_trendB

📈 Compare relative search/shopping-click trends of several book brands on one common scale (anchor keyword rescaling across batches). Values are relative indexes, not counts. Supports dryRun, call budget and xlsx/csv export. (도서 브랜드 여러 개의 검색어 트렌드 또는 쇼핑 클릭 추이를 기준 브랜드로 환산해 한 척도로 비교. 값은 상대 지수)

Inputs: brands (required), source (required), endDate (required), timeUnit (required), +10 more.

brand_mentionsA

📝 Collect blog/cafe/web posts that mention book brands, count them per month (approximate sample), and list co-mentioned candidate terms with examples. Candidate terms are not verified brands — judge them yourself. Supports dryRun, call budget and xlsx/csv export. (도서 브랜드를 언급한 블로그/카페/웹 글을 수집해 월별 집계와 동시 언급 후보 단어를 제공)

Inputs: brands (required), dryRun, confirm, sources, +7 more.

datalab_searchB

📊 Analyze search keyword trends over time using Naver DataLab. Track popularity changes, seasonal patterns, and compare multiple keywords. Perfect for market research and trend analysis. (네이버 데이터랩 검색어 트렌드 분석)

Inputs: endDate (required), timeUnit (required), startDate (required), keywordGroups (required).

datalab_shopping_by_ageA

👶👦👨👴 Analyze shopping trends by age groups (10s, 20s, 30s, 40s, 50s, 60s+). Use find_category first. BUSINESS CASES: Age-targeted products, generational preferences, lifecycle marketing. EXAMPLE: '개발 도구는 어느 연령대가 많이 구매하나?' (연령별 쇼핑 트렌드 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: ages (required), endDate (required), category (required), timeUnit (required), +1 more.

datalab_shopping_by_deviceA

📱 Analyze shopping trends by device (PC vs Mobile). Use find_category first. BUSINESS CASES: Mobile commerce strategy, responsive design priority, device-specific campaigns. EXAMPLE: 'PC 사용자가 더 많이 구매하는 카테고리는?' (기기별 쇼핑 트렌드 분석 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: device (required), endDate (required), category (required), timeUnit (required), +1 more.

datalab_shopping_by_genderA

👥 Analyze shopping trends by gender (Male vs Female). Use find_category first. BUSINESS CASES: Gender-targeted marketing, product positioning, demographic analysis. EXAMPLE: '화장품 쇼핑에서 남녀 비율은?' (성별 쇼핑 트렌드 분석 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: gender (required), endDate (required), category (required), timeUnit (required), +1 more.

datalab_shopping_categoryA

🛍️ STEP 2: Analyze shopping category trends over time. Use find_category first to get category codes. BUSINESS CASES: Market size analysis, seasonal trend identification, category performance comparison. EXAMPLE: Compare '패션의류' vs '화장품' trends over 6 months. (네이버 쇼핑 카테고리별 트렌드 분석 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: endDate (required), category (required), timeUnit (required), startDate (required).

datalab_shopping_keyword_by_ageB

👶👦👨👴🔍 Analyze keyword performance by age groups within shopping categories. Use find_category first to get category codes. Perfect for age-targeted marketing and understanding generational shopping preferences. (쇼핑 키워드 연령별 트렌드 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: ages (required), endDate (required), keyword (required), category (required), +2 more.

datalab_shopping_keyword_by_deviceB

📱🔍 Analyze keyword performance by device within shopping categories. Use find_category first to get category codes. Perfect for understanding mobile vs desktop shopping behavior for specific products. (쇼핑 키워드 기기별 트렌드 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: device (required), endDate (required), keyword (required), category (required), +2 more.

datalab_shopping_keyword_by_genderA

👥🔍 Analyze keyword performance by gender within shopping categories. Use find_category first to get category codes. Essential for gender-targeted marketing and product positioning strategies. (쇼핑 키워드 성별 트렌드 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: gender (required), endDate (required), keyword (required), category (required), +2 more.

datalab_shopping_keywordsA

🔍 Compare specific keywords within a shopping category. Use find_category first. BUSINESS CASES: Product keyword optimization, competitor analysis, search trend identification. EXAMPLE: Within '패션' category, compare '원피스' vs '자켓' vs '드레스' trends. (카테고리 내 키워드 비교 - 먼저 find_category 도구로 카테고리 코드를 찾으세요)

Inputs: endDate (required), keyword (required), category (required), timeUnit (required), +1 more.

find_categoryA

🚀 STEP 1: Find shopping categories with Korean search terms. Search in KOREAN (패션, 화장품, 가전제품, etc.) to find category codes needed for datalab tools. Smart fuzzy matching finds similar categories even with partial matches. (카테고리 검색: 한국어로 검색하여 데이터랩 분석에 필요한 카테고리 코드를 찾아주는 필수 도구)

Inputs: query (required), max_results.

search_blogA

✍️ Search personal blogs and reviews for authentic user experiences. Great for product reviews, personal stories, detailed tutorials, and real user opinions. Find genuine Korean perspectives. (네이버 블로그 검색 - 실제 사용자 후기와 개인적 경험)