MCP Kakao Local

Instructions

Implementation Reference

• src/mcp_kakao_local/server.py:65-97 (handler)

  MCP tool handler for 'search_by_keyword'. Defines input schema with Pydantic Fields, performs validation assertions, calls the KakaoLocalClient helper, and handles exceptions. This is the primary execution logic for the tool.
  @mcp.tool(description="Searches for places related to the keyword") async def search_by_keyword( keyword: str = Field(description="keyword used to search for places", min_length=1), category_group_code: CategoryGroupCode | None = Field( None, description="category used for filtering results (CategoryGroupCode resource)" ), center_coordinate: Coordinate | None = Field( None, description="longitude and latitude of a center" ), radius_from_center: int | None = Field( None, description="search radius from the center in meters", gt=0 ), page: int = Field(1, description="page number of result", ge=1), ) -> LocationSearchResponse: """ Returns: LocationSearchResponse: An object containing metadata and a list of places. """ if center_coordinate: assert radius_from_center is not None if radius_from_center: assert center_coordinate is not None try: return await kakao_local_client.search_by_keyword( keyword, category_group_code, center_coordinate, radius_from_center, page=page, ) except Exception as ex: return {"success": False, "error": str(ex)}
• src/mcp_kakao_local/kakao_local_client.py:40-63 (helper)

  Helper function in KakaoLocalClient that constructs the API request parameters and makes the HTTP GET request to Kakao's /search/keyword endpoint, then parses the response into LocationSearchResponse.
  async def search_by_keyword( self, keyword: str, category_group_code: CategoryGroupCode | None, center: Coordinate | None, radius: int | None, page: int = 1, size: int = 10, sort_option: LocationSortOption = LocationSortOption.ACCURACY, ) -> LocationSearchResponse: """https://developers.kakao.com/docs/latest/ko/local/dev-guide#search-by-keyword""" path = f"{self.BASE_URL}/search/keyword" params = { "query": keyword, "category_group_code": category_group_code.name if category_group_code else None, "x": center.longitude if center else None, "y": center.latitude if center else None, "radius": radius if radius else None, "page": page, "size": size, "sort": sort_option.value, } response_json = await self._get(path, {k: v for k, v in params.items() if v is not None}) return LocationSearchResponse(**response_json)
• src/mcp_kakao_local/models.py:87-90 (schema)

  Pydantic model defining the output schema for the search_by_keyword tool response, including metadata and list of place documents.
  class LocationSearchResponse(BaseModel): meta: Meta = Field(description="Response metadata") documents: list[PlaceDocument] = Field(description="List of places")
• src/mcp_kakao_local/models.py:6-9 (schema)

  Pydantic model for coordinate input used in search_by_keyword tool parameters.
  class Coordinate(BaseModel): longitude: str latitude: str
• src/mcp_kakao_local/models.py:16-35 (schema)

  Enum defining valid category_group_code values used as input parameter type in search_by_keyword tool.
  class CategoryGroupCode(Enum): MT1 = "대형마트 (Large Mart, Grocery Store)" CS2 = "편의점 (Convenience Store)" PS3 = "어린이집, 유치원 (Daycare, Kindergarten)" SC4 = "학교 (School)" AC5 = "학원 (Academy/Private Institute)" PK6 = "주차장 (Parking Lot)" OL7 = "주유소, 충전소 (Gas Station, Charging Station)" SW8 = "지하철역 (Subway Station)" BK9 = "은행 (Bank)" CT1 = "문화시설 (Cultural Facility)" AG2 = "중개업소 (Agency, e.g. Real Estate)" PO3 = "공공기관 (Public Institution)" AT4 = "관광명소 (Tourist Attraction)" AD5 = "숙박 (Accommodation)" FD6 = "음식점 (Restaurant)" CE7 = "카페 (Cafe)" HP8 = "병원 (Hospital)" PM9 = "약국 (Pharmacy)"