Naver Search MCP Server

Instructions

Implementation Reference

• server.py:498-511 (handler)

  The main handler function for the 'search_local' tool. It prepares parameters specific to Naver's local search API (noting API limits like display<=5 and start=1) and calls the shared _make_api_call helper to fetch and format results from 'local.json' endpoint.
  async def search_local(query: str, display: int = 5, page: int = 1, sort: str = "random") -> str: """ Searches for local business information using the given keyword. (display maximum 5, start maximum 1) sort='random'/'comment' is supported. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 5. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "random" (random). """ display = min(display, 5) # API 제약 조건 적용 start = 1 # 지역 API는 항상 start=1 params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("local.json", params, LocalResult, "Local")
• server.py:494-497 (registration)

  MCP tool registration decorator for 'search_local', specifying the name and description.
  @mcp.tool( name="search_local", description="Searches for local business information using the given keyword. (display maximum 5, start maximum 1) sort='random'/'comment' is supported." )
• server.py:97-104 (schema)

  Pydantic model defining the structure of individual local search result items used for output validation and formatting.
  class LocalItem(BaseItem): category: Optional[str] = None description: Optional[str] = None telephone: Optional[str] = None address: Optional[str] = None roadAddress: Optional[str] = None mapx: Optional[str] = None mapy: Optional[str] = None
• server.py:132-132 (schema)

  Pydantic model for the overall local search response, inheriting common fields and specifying items as List[LocalItem].
  class LocalResult(SearchResultBase): items: List[LocalItem]
• server.py:348-511 (helper)

  Helper function to calculate 'start' parameter for paginated APIs, though overridden for local search.
  def calculate_start(page: int, display: int) -> int: """Calculates the start value for the API call based on the page number and display count.""" if page < 1: page = 1 start = (page - 1) * display + 1 # 네이버 API의 start 최대값(1000) 제한 고려 return min(start, 1000) # --- MCP Tool 정의 (페이지네이션, 동적 Prompt 적용) --- # 1. 블로그 검색 @mcp.tool( name="search_blog", description="Searches for blogs on Naver using the given keyword. The page parameter allows for page navigation." ) async def search_blog(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for blogs on Naver using the given keyword. The page parameter allows for page navigation. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): 정렬 기준. 기본값은 "sim" (유사도). """ start = calculate_start(page, display) display = min(display, 100) # display 최대값 제한 params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("blog.json", params, BlogResult, "Blog") # 2. 뉴스 검색 @mcp.tool( name="search_news", description="Searches for news on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date' is supported." ) async def search_news(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for news on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date' is supported. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "sim" (similarity). """ start = calculate_start(page, display) display = min(display, 100) params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("news.json", params, NewsResult, "News") # 3. 책 검색 (기본) @mcp.tool( name="search_book", description="Searches for book information on Naver using the given keyword. The page parameter allows for page navigation." ) async def search_book(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for book information on Naver using the given keyword. The page parameter allows for page navigation. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "sim" (similarity). """ start = calculate_start(page, display) display = min(display, 100) params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("book.json", params, BookResult, "Book") # 4. 성인 검색어 판별 (페이지네이션 없음) @mcp.tool( name="check_adult_query", description="Determines if the input query is an adult search term." ) async def check_adult_query(query: str) -> str: """ Determines if the input query is an adult search term. Args: query (str): The keyword to search for """ params = {"query": query} return await _make_api_call("adult.json", params, AdultResult, "Adult Search Term") # 5. 백과사전 검색 @mcp.tool( name="search_encyclopedia", description="Searches for encyclopedia information on Naver using the given keyword. The page parameter allows for page navigation." ) async def search_encyclopedia(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for encyclopedia information on Naver using the given keyword. The page parameter allows for page navigation. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "sim" (similarity). """ start = calculate_start(page, display) display = min(display, 100) params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("encyc.json", params, EncycResult, "Encyclopedia") # 6. 카페글 검색 @mcp.tool( name="search_cafe_article", description="Searches for cafe articles on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date' is supported." ) async def search_cafe_article(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for cafe articles on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date' is supported. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "sim" (similarity). """ start = calculate_start(page, display) display = min(display, 100) params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("cafearticle.json", params, CafeArticleResult, "Cafe Article") # 7. 지식iN 검색 @mcp.tool( name="search_kin", description="Searches for knowledgeiN Q&A on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date'/'point' is supported." ) async def search_kin(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str: """ Searches for knowledgeiN Q&A on Naver using the given keyword. The page parameter allows for page navigation and sort='sim'/'date'/'point' is supported. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 10. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "sim" (similarity). """ start = calculate_start(page, display) display = min(display, 100) params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("kin.json", params, KinResult, "KnowledgeiN") # 8. 지역 검색 (페이지네이션 미지원 API) @mcp.tool( name="search_local", description="Searches for local business information using the given keyword. (display maximum 5, start maximum 1) sort='random'/'comment' is supported." ) async def search_local(query: str, display: int = 5, page: int = 1, sort: str = "random") -> str: """ Searches for local business information using the given keyword. (display maximum 5, start maximum 1) sort='random'/'comment' is supported. Args: query (str): The keyword to search for display (int, optional): The number of results to display. Default is 5. page (int, optional): The starting page number. Default is 1. sort (str, optional): The sorting criteria. Default is "random" (random). """ display = min(display, 5) # API 제약 조건 적용 start = 1 # 지역 API는 항상 start=1 params = {"query": query, "display": display, "start": start, "sort": sort} return await _make_api_call("local.json", params, LocalResult, "Local")