IP Geolocation MCP Server

Instructions

Implementation Reference

• src/client.ts:211-245 (handler)

  The core API handler function for timezone conversion.

  export async function convertTimezone(params: {
    time?: string;
    tz_from?: string;
    tz_to?: string;
    lat_from?: string;
    long_from?: string;
    lat_to?: string;
    long_to?: string;
    location_from?: string;
    location_to?: string;
    iata_from?: string;
    iata_to?: string;
    icao_from?: string;
    icao_to?: string;
    locode_from?: string;
    locode_to?: string;
  }): Promise<unknown> {
    return request("/v3/timezone/convert", {
      time: params.time,
      tz_from: params.tz_from,
      tz_to: params.tz_to,
      lat_from: params.lat_from,
      long_from: params.long_from,
      lat_to: params.lat_to,
      long_to: params.long_to,
      location_from: params.location_from,
      location_to: params.location_to,
      iata_from: params.iata_from,
      iata_to: params.iata_to,
      icao_from: params.icao_from,
      icao_to: params.icao_to,
      locode_from: params.locode_from,
      locode_to: params.locode_to,
    });
  }

• src/tools/timezone.ts:106-266 (registration)

  Registration of the convert_timezone MCP tool.

    server.registerTool(
      "convert_timezone",
      {
        title: "Timezone Conversion",
        annotations: {
          readOnlyHint: true,
        },
        description: `Convert time between two locations via GET /v3/timezone/convert. Works on free and paid plans. Cost: 1 credit.
  
  Specify source and destination by IANA timezone, coordinates, location, airport code, or UN/LOCODE. Returns original time, converted time, diff_hour, and diff_min.`,
        inputSchema: {
          time: z
            .string()
            .optional()
            .describe(
              "Time to convert in yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss format. Defaults to current time."
            ),
          tz_from: z
            .string()
            .optional()
            .describe("Source IANA timezone name (e.g. America/New_York)."),
          tz_to: z
            .string()
            .optional()
            .describe("Destination IANA timezone name (e.g. Asia/Tokyo)."),
          lat_from: z
            .string()
            .optional()
            .describe("Source latitude. Use with long_from."),
          long_from: z
            .string()
            .optional()
            .describe("Source longitude. Use with lat_from."),
          lat_to: z
            .string()
            .optional()
            .describe("Destination latitude. Use with long_to."),
          long_to: z
            .string()
            .optional()
            .describe("Destination longitude. Use with lat_to."),
          location_from: z
            .string()
            .optional()
            .describe("Source city or address string."),
          location_to: z
            .string()
            .optional()
            .describe("Destination city or address string."),
          iata_from: z
            .string()
            .optional()
            .describe("Source 3-letter IATA airport code."),
          iata_to: z
            .string()
            .optional()
            .describe("Destination 3-letter IATA airport code."),
          icao_from: z
            .string()
            .optional()
            .describe("Source 4-letter ICAO airport code."),
          icao_to: z
            .string()
            .optional()
            .describe("Destination 4-letter ICAO airport code."),
          locode_from: z
            .string()
            .optional()
            .describe("Source 5-character UN/LOCODE."),
          locode_to: z
            .string()
            .optional()
            .describe("Destination 5-character UN/LOCODE."),
        },
      },
      async (params) => {
        try {
          const sourceCoordinateError = validateCoordinatePairNamed(
            params.lat_from,
            params.long_from,
            "lat_from",
            "long_from",
            "convert_timezone"
          );
          if (sourceCoordinateError) {
            throw new Error(sourceCoordinateError);
          }
  
          const destinationCoordinateError = validateCoordinatePairNamed(
            params.lat_to,
            params.long_to,
            "lat_to",
            "long_to",
            "convert_timezone"
          );
          if (destinationCoordinateError) {
            throw new Error(destinationCoordinateError);
          }
  
          const hasSource = hasAnyValue([
            params.tz_from,
            params.lat_from,
            params.long_from,
            params.location_from,
            params.iata_from,
            params.icao_from,
            params.locode_from,
          ]);
          if (!hasSource) {
            throw new Error(
              "convert_timezone: provide at least one source selector (tz_from, lat_from/long_from, location_from, iata_from, icao_from, or locode_from)."
            );
          }
  
          const hasDestination = hasAnyValue([
            params.tz_to,
            params.lat_to,
            params.long_to,
            params.location_to,
            params.iata_to,
            params.icao_to,
            params.locode_to,
          ]);
          if (!hasDestination) {
            throw new Error(
              "convert_timezone: provide at least one destination selector (tz_to, lat_to/long_to, location_to, iata_to, icao_to, or locode_to)."
            );
          }
  
          const timeError = validateTimezoneConversionTime(params.time, "time");
          if (timeError) {
            throw new Error(timeError);
          }
  
          const result = await convertTimezone({
            time: params.time,
            tz_from: params.tz_from,
            tz_to: params.tz_to,
            lat_from: params.lat_from,
            long_from: params.long_from,
            lat_to: params.lat_to,
            long_to: params.long_to,
            location_from: params.location_from,
            location_to: params.location_to,
            iata_from: params.iata_from,
            iata_to: params.iata_to,
            icao_from: params.icao_from,
            icao_to: params.icao_to,
            locode_from: params.locode_from,
            locode_to: params.locode_to,
          });
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );