IP Geolocation MCP Server

Instructions

Implementation Reference

• src/client.ts:247-266 (handler)

  Actual API handler implementation for get_astronomy that calls the remote service.

  export async function getAstronomy(params: {
    lat?: string;
    long?: string;
    location?: string;
    ip?: string;
    date?: string;
    elevation?: string;
    time_zone?: string;
    lang?: string;
  }): Promise<unknown> {
    return request("/v3/astronomy", {
      lat: params.lat,
      long: params.long,
      location: params.location,
      ip: params.ip,
      date: params.date,
      elevation: params.elevation,
      time_zone: params.time_zone,
      lang: params.lang,
    });

• src/tools/astronomy.ts:43-141 (registration)

  Tool registration and handler wrapper for get_astronomy.

    server.registerTool(
      "get_astronomy",
      {
        title: "Astronomy Data",
        annotations: {
          readOnlyHint: true,
        },
        description: `Astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. Look up by coordinates, location, or IP, with optional date and elevation.
  
  Returns location details plus astronomy data such as sunrise, sunset, moonrise, moonset, morning and evening twilight blocks, day length, sun and moon status, positions, and moon phase fields.
  
  The lang parameter for non-English location field responses is available on paid plans only. On free plans, using a non-English lang value returns 401 Unauthorized.`,
        inputSchema: {
          lat: z
            .string()
            .optional()
            .describe(
              "Latitude coordinate. Highest priority. Must be used with long."
            ),
          long: z
            .string()
            .optional()
            .describe("Longitude coordinate. Must be used with lat."),
          location: z
            .string()
            .optional()
            .describe("City or address string (e.g. San Francisco, CA)."),
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 or IPv6 address to get astronomy data for that IP's location."
            ),
          date: z
            .string()
            .optional()
            .describe("Date in YYYY-MM-DD format. Defaults to today."),
          elevation: z
            .string()
            .optional()
            .describe(
              "Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations for higher accuracy."
            ),
          time_zone: z
            .string()
            .optional()
            .describe(
              "IANA timezone name to express times in (e.g. America/New_York). If set, time fields include full date instead of just time."
            ),
          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_astronomy"
          );
          if (coordinateError) {
            throw new Error(coordinateError);
          }
  
          const dateError = validateIsoDate(params.date, "date");
          if (dateError) {
            throw new Error(dateError);
          }
  
          const elevationError = validateElevation(params.elevation, "elevation");
          if (elevationError) {
            throw new Error(elevationError);
          }
  
          const result = await getAstronomy({
            lat: params.lat,
            long: params.long,
            location: params.location,
            ip: params.ip,
            date: params.date,
            elevation: params.elevation,
            time_zone: params.time_zone,
            lang: params.lang,
          });
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );