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")