Korea Tourism API MCP Server

Instructions

Implementation Reference

• src/mcp_tourism/server.py:285-414 (handler)

  The function 'get_tourism_by_area' implements the logic to fetch tourism data from the Korea Tourism API based on area and category filters.

  async def get_tourism_by_area(
      area_code: str,
      sigungu_code: str | None = None,
      content_type: str | None = None,
      language: str | None = None,
      page: int = 1,
      rows: int = 20,
      filter: list[str] | None = None,
  ) -> dict:
      """
      Browse tourism information by geographic areas in Korea.
  
      This tool retrieves tourism items from a specific geographic area in Korea.
      It allows filtering by area code, sigungu (district) code, and content type
      to find relevant tourism information in a particular region.
  
      Args:
          area_code (str): Area code. Valid values:
              - "1" (Seoul)
              - "2" (Incheon)
              - "3" (Daejeon)
              - "4" (Daegu)
              - "5" (Gwangju)
              - "6" (Busan)
              - "7" (Ulsan)
              - "8" (Sejong)
              - "31" (Gyeonggi-do)
              - "32" (Gangwon-do)
              - "33" (Chungcheongbuk-do)
              - "34" (Chungcheongnam-do)
              - "35" (Gyeongsangbuk-do)
              - "36" (Gyeongsangnam-do)
              - "37" (Jeonbuk-do)
              - "38" (Jeollanam-do)
              - "39" (Jeju-do)
          sigungu_code (str, optional): Sigungu (district) code within the area
          content_type (str, optional): Type of content to filter. Valid values:
              - "Tourist Attraction" (default)
              - "Cultural Facility"
              - "Festival Event"
              - "Leisure Activity"
              - "Accommodation"
              - "Shopping"
              - "Restaurant"
              - "Transportation"
          language (str, optional): Language for results (default: "en"). Supported:
              - "en" (English)
              - "jp" (Japanese)
              - "zh-cn" (Simplified Chinese)
              - "zh-tw" (Traditional Chinese)
              - "de" (German)
              - "fr" (French)
              - "es" (Spanish)
              - "ru" (Russian)
          page (int, optional): Page number for pagination (default: 1, min: 1)
          rows (int, optional): Number of items per page (default: 20, max: 100)
          filter (list[str], optional): List of keys to include in each result item (whitelist).
              - If filter is None or an empty list ([]), all fields are returned.
              - If filter contains values, only the specified keys will be included in each item, and all other keys will be removed.
  
      Returns:
          dict: Area-based tourism information with structure:
          {
              "total_count": int,     # Total number of matching items
              "num_of_rows": int,     # Number of items per page
              "page_no": int,         # Current page number
              "items": [              # List of tourism items
                  {
                      "title": str,           # Name of the attraction/place
                      "addr1": str,           # Primary address
                      "addr2": str,           # Secondary address
                      "areacode": str,        # Area code
                      "sigungucode": str,     # Sigungu code
                      "cat1": str,            # Category 1 code
                      "cat2": str,            # Category 2 code
                      "cat3": str,            # Category 3 code
                      "contentid": str,       # Unique content ID
                      "contenttypeid": str,   # Content type ID
                      "createdtime": str,     # Creation timestamp
                      "modifiedtime": str,    # Last modified timestamp
                      "tel": str,             # Phone number
                      "firstimage": str,      # URL of main image
                      "firstimage2": str,     # URL of thumbnail image
                      "mapx": str,            # Longitude
                      "mapy": str,            # Latitude
                      "zipcode": str,         # Postal code
                      "mlevel": str           # Map level
                  }
                  # ... more items
              ]
          }
  
      Example:
          get_tourism_by_area("1", "1", "Tourist Attraction", "en", 1, 20)
      """
      # Validate and convert content_type
      content_type_id = None
      if content_type:
          content_type_id = next(
              (
                  k
                  for k, v in CONTENTTYPE_ID_MAP.items()
                  if v.lower() == content_type.lower()
              ),
              None,
          )
          if content_type_id is None:
              valid_types = ", ".join(CONTENTTYPE_ID_MAP.values())
              raise ValueError(
                  f"Invalid content_type: '{content_type}'. Valid types are: {valid_types}"
              )
  
      # Call the API client and return dict directly
      result = await get_api_client().get_area_based_list(
          area_code=area_code,
          sigunguCode=sigungu_code,
          content_type_id=content_type_id,
          language=language,
          page=page,
          rows=rows,
      )
      if filter:
          # Apply additional filtering if provided
          filter_items = []
          for item in result.get("items", []):
              item = {k: v for k, v in item.items() if k in filter}
              filter_items.append(item)
          result["items"] = filter_items
      return result

• src/mcp_tourism/server.py:284-285 (registration)

  The 'get_tourism_by_area' tool is registered with the MCP server using the '@mcp.tool' decorator.

  @mcp.tool
  async def get_tourism_by_area(