MCP Kakao Local

Instructions

Implementation Reference

• src/mcp_kakao_local/server.py:124-138 (handler)

  The handler function for the 'get_place' MCP tool. It is registered with @mcp.tool and handles input validation via Pydantic Field, then delegates to KakaoLocalClient.get_place_details.

  @mcp.tool(description="Fetches details for a place such as name, address, reviews, photos and etc")
  async def get_place(
    place_id: int = Field(
      description="ID of a place, which is document ID in location search results", ge=1
    ),
  ) -> dict:
    """
    Returns:
      PlaceDetailResponse: An object containing details of the place
    """
    try:
      return await kakao_local_client.get_place_details(place_id)
    except Exception as ex:
      return {"success": False, "error": str(ex)}

• src/mcp_kakao_local/kakao_local_client.py:88-107 (helper)

  The core helper function that performs the HTTP request to Kakao's place API to fetch detailed information for the given place_id and parses it into PlaceDetailResponse.

  async def get_place_details(self, place_id: int) -> PlaceDetailResponse:
    headers = {
      "Accept": "application/json, text/plain, */*",
      "Accept-Encoding": "gzip, deflate, br",
      "Accept-Language": "en-US,en;q=0.9",
      "Connection": "keep-alive",
      "Dnt": "1",
      "Origin": "https://place.map.kakao.com",
      "Referer": "https://place.map.kakao.com/",
      "Pf": "web",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
    }
    async with httpx.AsyncClient(headers=headers, http2=True) as client:
      response = await client.get(f"https://place-api.map.kakao.com/places/panel3/{place_id}")
      try:
        response_json = response.raise_for_status().json()
        return PlaceDetailResponse(**response_json)
      except httpx.HTTPError as exc:
        self._handle_response_status(response.status_code, exc)

• src/mcp_kakao_local/models.py:105-114 (schema)

  Pydantic model defining the output schema for place details, used by the get_place_details helper.

  class PlaceDetailResponse(BaseModel):
    menu: dict = Field({}, description="Menus if the place has menus")
    summary: PlaceSummary = Field(description="Summary of the place")
    business_hours: dict = Field(description="Details of business hours")
    photos: dict = Field(description="Contains counts (metadata) and photos of the place")
    blog_review: dict = Field(description="Review of the place in blogs")
    kakaomap_review: dict = Field(description="Review of the place on Kakap Map (optional)")
    find_way: dict = Field(description="Transit information nearby the place")
    place_add_info: dict = Field(description="Additional information of the place")

• src/mcp_kakao_local/server.py:124-124 (registration)

  The @mcp.tool decorator registers the 'get_place' function as an MCP tool with its description.

  @mcp.tool(description="Fetches details for a place such as name, address, reviews, photos and etc")

• src/mcp_kakao_local/server.py:126-128 (schema)

  Input schema validation for the place_id parameter using Pydantic Field.

  place_id: int = Field(
    description="ID of a place, which is document ID in location search results", ge=1
  ),