IMF Data MCP Server

Instructions

Implementation Reference

• imf_data_mcp/__init__.py:122-146 (handler)

  The main handler function for the 'fetch_bop_data' tool. It is registered via the @mcp.tool() decorator and implements the logic to fetch Balance of Payments (BOP) time series data from the IMF API, process it using process_imf_data, or return an error.
  @mcp.tool() def fetch_bop_data(freq: str, country: str, indicator: str, start: str | int, end: str | int) -> str: """ Retrieves compact format time series data from the BOP database based on the input parameters. Args: freq (str): Frequency (e.g., "A" for annual, "Q" for quarterly, "M" for monthly). country (str): Country code, multiple country codes can be connected with "+". indicator (str): Indicator code. start (str | int): Start year. end (str | int): End year. Returns: str: Description of the queried data. Do not perform further analysis or retry if the query fails. """ dimensions = f"{freq}.{country}.{indicator}" url = f"http://dataservices.imf.org/REST/SDMX_JSON.svc/CompactData/BOP/{dimensions}?startPeriod={start}&endPeriod={end}" try: response = requests.get(url) response.raise_for_status() data = response.json() return process_imf_data(data) except Exception as e: return f"Error fetching BOP data: {str(e)}"
• imf_data_mcp/utils.py:1-52 (helper)

  Helper utility function imported and used by fetch_bop_data (and other tools) to parse the IMF JSON response into a human-readable string summary of the time series data.
  def process_imf_data(json_data: dict) -> str: """ Process IMF data and return a string with the information. :param: json_data(dict): JSON data from the IMF API :return: (str) A string with the information from the JSON data """ try: json_data = json_data["CompactData"] dataset = json_data["DataSet"] series_list = dataset["Series"] if isinstance(series_list, dict): series_list = [series_list] elif not isinstance(series_list, list): return f"Error: Expected series_list to be a list but got {type(series_list)}" output_texts = [] for series in series_list: if series is None: output_texts.append("Warning: No indicator value.") continue country = series.get("@REF_AREA", None) obs = series.get("Obs", {}) if isinstance(obs, dict): obs = [obs] elif not isinstance(obs, list): return f"Error: Expected obs to be a list but got {type(obs)}" for _obs in obs: if _obs is None: output_texts.append( f"Warning: No indicator value for {country} in that Year, You should not try to access the data of this country." ) continue time_period = _obs.get("@TIME_PERIOD", "that Year") obs_value = _obs.get("@OBS_VALUE") if obs_value is not None: text = f"In {time_period}, {country} had an indicator value of {float(obs_value):.2f}." output_texts.append(text) else: output_texts.append(f"Warning: No indicator value for {country} in {time_period}.") return "\n".join(output_texts) except KeyError as e: return f"Error processing IMF data: Missing key {str(e)}" except Exception as e: return f"Error processing IMF data: {str(e)}"
• imf_data_mcp/__init__.py:122-122 (registration)

  The @mcp.tool() decorator registers the fetch_bop_data function as an MCP tool, using the function name as the tool name.
  @mcp.tool()