IP Geolocation MCP Server

Instructions

Implementation Reference

• src/client.ts:187-209 (handler)

  The core function that performs the actual API request to /v3/timezone.

  export async function getTimezone(params: {
    tz?: string;
    lat?: string;
    long?: string;
    location?: string;
    ip?: string;
    iata_code?: string;
    icao_code?: string;
    lo_code?: string;
    lang?: string;
  }): Promise<unknown> {
    return request("/v3/timezone", {
      tz: params.tz,
      lat: params.lat,
      long: params.long,
      location: params.location,
      ip: params.ip,
      iata_code: params.iata_code,
      icao_code: params.icao_code,
      lo_code: params.lo_code,
      lang: params.lang,
    });
  }

• src/tools/timezone.ts:13-104 (registration)

  MCP tool registration for 'get_timezone', which includes schema definition and a handler that calls the client-side 'getTimezone' function.

    server.registerTool(
      "get_timezone",
      {
        title: "Timezone Lookup",
        annotations: {
          readOnlyHint: true,
        },
        description: `Timezone lookup via GET /v3/timezone. Works on free and paid plans. Cost: 1 credit. Look up by IANA timezone, coordinates, location, IP, airport code, or UN/LOCODE.
  
  Returns location details plus a time_zone object with offsets, current time values, date/time variants, abbreviations, DST status, and transition dates. Airport lookups also include airport details.
  
  The lang parameter for non-English responses is available on paid plans only. On free plans, using a non-English lang value returns 401 Unauthorized.`,
        inputSchema: {
          tz: z
            .string()
            .optional()
            .describe(
              "IANA timezone name (e.g. America/New_York, Europe/London). Highest priority if multiple params provided."
            ),
          lat: z
            .string()
            .optional()
            .describe("Latitude coordinate. Must be used together with long."),
          long: z
            .string()
            .optional()
            .describe("Longitude coordinate. Must be used together with lat."),
          location: z
            .string()
            .optional()
            .describe("City or address string (e.g. London, UK)."),
          ip: z
            .string()
            .optional()
            .describe("IPv4 or IPv6 address to get timezone for."),
          iata_code: z
            .string()
            .optional()
            .describe(
              "3-letter IATA airport code (e.g. JFK, LHR). Returns airport details in the response."
            ),
          icao_code: z
            .string()
            .optional()
            .describe(
              "4-letter ICAO airport code (e.g. KJFK, EGLL). Returns airport details in the response."
            ),
          lo_code: z
            .string()
            .optional()
            .describe("5-character UN/LOCODE (e.g. DEBER, USNYC)."),
          lang: z
            .string()
            .optional()
            .describe(
              "Response language for location fields in IP-based lookups (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt). Paid plans only. Free plan returns 401 for non-English language values."
            ),
        },
      },
  
      async (params) => {
        try {
          const coordinateError = validateCoordinatePair(
            params.lat,
            params.long,
            "get_timezone"
          );
          if (coordinateError) {
            throw new Error(coordinateError);
          }
  
          const result = await getTimezone({
            tz: params.tz,
            lat: params.lat,
            long: params.long,
            location: params.location,
            ip: params.ip,
            iata_code: params.iata_code,
            icao_code: params.icao_code,
            lo_code: params.lo_code,
            lang: params.lang,
          });
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );