UNHCR Population Data MCP Server

Instructions

    Get RSD application data from UNHCR.

    Args:
        coo: Country of origin filter (ISO3 code, comma-separated for multiple)
        coa: Country of asylum filter (ISO3 code, comma-separated for multiple)
        year: Year filter (comma-separated for multiple years) - defaults to 2025
        coo_all: Set to True when analyzing the ORIGIN COUNTRIES of asylum seekers
        coa_all: Set to True when analyzing the ASYLUM COUNTRIES where applications were filed

    Returns:
        RSD application data from UNHCR API
    

Implementation Reference

• src/unhcr_mcp/server.py:175-198 (handler)

  Primary handler and registration for the get_rsd_applications tool via @server.tool() decorator. Proxies to UNHCRAPIClient.get_asylum_applications.

  @server.tool()
  def get_rsd_applications(
      coo: str | None = None,
      coa: str | None = None,
      year: str | int | None = None,
      coo_all: bool = False,
      coa_all: bool = False,
  ) -> dict[str, Any]:
      """
      Get RSD application data from UNHCR.
  
      Args:
          coo: Country of origin filter (ISO3 code, comma-separated for multiple)
          coa: Country of asylum filter (ISO3 code, comma-separated for multiple)
          year: Year filter (comma-separated for multiple years) - defaults to 2025
          coo_all: Set to True when analyzing the ORIGIN COUNTRIES of asylum seekers
          coa_all: Set to True when analyzing the ASYLUM COUNTRIES where applications were filed
  
      Returns:
          RSD application data from UNHCR API
      """
      return api_client.get_asylum_applications(
          coo=coo, coa=coa, year=year, coo_all=coo_all, coa_all=coa_all
      )

• src/unhcr_mcp/server.py:90-93 (helper)

  Helper method in UNHCRAPIClient class that calls the generic _fetch for the 'asylum-applications' UNHCR endpoint.

  def get_asylum_applications(self, coo: Optional[str] = None, coa: Optional[str] = None, 
                             year: Optional[Union[str, int]] = None,
                             coo_all: bool = False, coa_all: bool = False) -> dict[str, Any]:
      return self._fetch("asylum-applications", coo=coo, coa=coa, year=year, coo_all=coo_all, coa_all=coa_all)

• src/unhcr_mcp/server.py:34-79 (helper)

  Core helper method in UNHCRAPIClient that performs HTTP requests to the UNHCR API with dynamic parameters for filtering by country, year, etc.

  def _fetch(self, endpoint: str,
           coo: Optional[str] = None,
           coa: Optional[str] = None,
           year: Optional[Union[str, int]] = None,
           coo_all: bool = False,
           coa_all: bool = False,
           pop_type: Optional[bool] = None) -> dict[str, Any]:
      """
      Generic function to fetch data from various UNHCR API endpoints.
      """
      params = {"cf_type": "ISO"}
      
      if coo:
          params["coo"] = coo
      if coa:
          params["coa"] = coa
      if coo_all:
          params["coo_all"] = "true"
      if coa_all:
          params["coa_all"] = "true"
      
      if pop_type is True:
          params["pop_type"] = "true"            
      
      if year is None:
          # Default to 2025 as per previous implementation logic
          params["year[]"] = "2025"
      else:
          year_str = str(year)
          if "," in year_str:
              years = [y.strip() for y in year_str.split(",")]
              params["year[]"] = years
          else:
              params["year[]"] = year_str
      
      url = f"{self.BASE_URL}/{endpoint}/"
      
      try:
          logger.info(f"Fetching UNHCR {endpoint} data with params: {params}")
          response = requests.get(url, params=params)
          response.raise_for_status()
          return response.json()
      except requests.RequestException as e:
          logger.error(f"Error fetching UNHCR {endpoint} data: {e}")
          return {"error": str(e), "status": "error"}

• src/unhcr_mcp/server.py:121-121 (registration)

  Instantiation of the UNHCRAPIClient used by the tool handlers.

  api_client = UNHCRAPIClient()