MCP Kakao Local

Instructions

Implementation Reference

• src/mcp_kakao_local/server.py:46-62 (handler)

  MCP tool handler for find_coordinates: validates inputs with Pydantic Fields, calls KakaoLocalClient.find_coordinates, handles empty results and exceptions, returns AddressResponse or error dict.

  @mcp.tool(description="Find coordinates of a given address")
  async def find_coordinates(
    address: str = Field(description="address to search for", min_length=1),
    page: int = Field(1, description="page number of result", ge=1),
  ) -> AddressResponse:
    """
    Returns:
      AddressResponse: An object containing metadata and a list of addresses
    """
    try:
      response = await kakao_local_client.find_coordinates(address, page=page)
      if len(response.documents) == 0:
        return {"success": False, "error": "No coordinates found. Check if the address is correct."}
  
      return response
    except Exception as ex:
      return {"success": False, "error": str(ex)}

• src/mcp_kakao_local/kakao_local_client.py:29-38 (helper)

  Core implementation in KakaoLocalClient: constructs API params, makes HTTP GET to Kakao Local API endpoint for address coordinates, parses JSON response into AddressResponse model.

  async def find_coordinates(self, address: str, page: int = 1, size: int = 10) -> AddressResponse:
    """https://developers.kakao.com/docs/latest/ko/local/dev-guide#address-coord"""
    path = f"{self.BASE_URL}/search/address"
    params = {
      "query": address,
      "page": page,
      "size": size,
    }
    response_json = await self._get(path, params)
    return AddressResponse(**response_json)

• src/mcp_kakao_local/models.py:92-94 (schema)

  Pydantic BaseModel schema for the tool's output: AddressResponse containing meta (paging info) and list of AddressDocument (each with address_name, type, x/y coordinates, etc.).

  class AddressResponse(BaseModel):
    meta: Meta = Field(description="Response metadata")
    documents: list[AddressDocument] = Field(description="List of addresses")

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

  Registration of the 'find_coordinates' tool via FastMCP's @mcp.tool decorator with description.

  @mcp.tool(description="Find coordinates of a given address")

• src/mcp_kakao_local/models.py:76-85 (schema)

  Pydantic model for individual address document in response: includes address_name, type, longitude (x), latitude (y), and address details.

  class AddressDocument(BaseModel):
    address_name: str = Field(description="street address or land-lot address (지번 주소)")
    address_type: Literal["REGION", "ROAD", "REGION_ADDR", "ROAD_ADDR"] = Field(
      description="type of address"
    )
    x: str = Field(description="longitude")
    y: str = Field(description="latitude")
    address: dict = Field(description="details of land-lot address (지번 주소)")
    road_address: dict = Field(description="details of street address")