ipgeolocation-io-mcp 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+export declare function getApiKey(): string;
+export declare class ApiError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare function getIpGeolocation(params: {
+    ip?: string;
+    lang?: string;
+    include?: string;
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare function getMyIp(): Promise<string>;
+export declare function getSecurity(params: {
+    ip?: string;
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare function getSecurityBulk(params: {
+    ips: string[];
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare 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>;
+export declare 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>;
+export declare function getAstronomy(params: {
+    lat?: string;
+    long?: string;
+    location?: string;
+    ip?: string;
+    date?: string;
+    elevation?: string;
+    time_zone?: string;
+    lang?: string;
+}): Promise<unknown>;
+export declare function getAsn(params: {
+    asn?: string;
+    ip?: string;
+    include?: string;
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare function getIpGeolocationBulk(params: {
+    ips: string[];
+    lang?: string;
+    include?: string;
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare function getAbuseContact(params: {
+    ip?: string;
+    fields?: string;
+    excludes?: string;
+}): Promise<unknown>;
+export declare function parseUserAgent(params: {
+    uaString: string;
+}): Promise<unknown>;
+export declare function parseUserAgentBulk(params: {
+    uaStrings: string[];
+}): Promise<unknown>;
+export declare function getAstronomyTimeSeries(params: {
+    lat?: string;
+    long?: string;
+    location?: string;
+    ip?: string;
+    dateStart: string;
+    dateEnd: string;
+    elevation?: string;
+    time_zone?: string;
+    lang?: string;
+}): Promise<unknown>;

package/dist/client.js

@@ -0,0 +1,173 @@
+const API_BASE = "https://api.ipgeolocation.io";
+let apiKey;
+export function getApiKey() {
+    if (!apiKey) {
+        apiKey = process.env.IPGEOLOCATION_API_KEY;
+    }
+    if (!apiKey) {
+        throw new Error("API key not configured. Set the IPGEOLOCATION_API_KEY environment variable.");
+    }
+    return apiKey;
+}
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ApiError";
+    }
+}
+async function request(path, params = {}, options = {}) {
+    const url = new URL(path, API_BASE);
+    if (!options.skipAuth) {
+        url.searchParams.set("apiKey", getApiKey());
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== "") {
+            url.searchParams.set(key, value);
+        }
+    }
+    const fetchOptions = {
+        method: options.method || "GET",
+        headers: {
+            Accept: "application/json",
+        },
+    };
+    if (options.body) {
+        fetchOptions.headers = {
+            ...fetchOptions.headers,
+            "Content-Type": "application/json",
+        };
+        fetchOptions.body = JSON.stringify(options.body);
+    }
+    const response = await fetch(url.toString(), fetchOptions);
+    if (!response.ok) {
+        let message;
+        try {
+            const text = await response.text();
+            message = text || response.statusText;
+        }
+        catch {
+            message = response.statusText;
+        }
+        throw new ApiError(response.status, `${response.status}: ${message}`);
+    }
+    return response.json();
+}
+export async function getIpGeolocation(params) {
+    return request("/v3/ipgeo", {
+        ip: params.ip,
+        lang: params.lang,
+        include: params.include,
+        fields: params.fields,
+        excludes: params.excludes,
+    });
+}
+export async function getMyIp() {
+    const response = await fetch(`${API_BASE}/v3/getip`);
+    if (!response.ok) {
+        throw new ApiError(response.status, "Failed to retrieve IP address");
+    }
+    const data = (await response.json());
+    return data.ip;
+}
+export async function getSecurity(params) {
+    return request("/v3/security", {
+        ip: params.ip,
+        fields: params.fields,
+        excludes: params.excludes,
+    });
+}
+export async function getSecurityBulk(params) {
+    return request("/v3/security-bulk", {
+        fields: params.fields,
+        excludes: params.excludes,
+    }, { method: "POST", body: { ips: params.ips } });
+}
+export async function getTimezone(params) {
+    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,
+    });
+}
+export async function convertTimezone(params) {
+    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,
+    });
+}
+export async function getAstronomy(params) {
+    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,
+    });
+}
+export async function getAsn(params) {
+    return request("/v3/asn", {
+        asn: params.asn,
+        ip: params.ip,
+        include: params.include,
+        fields: params.fields,
+        excludes: params.excludes,
+    });
+}
+export async function getIpGeolocationBulk(params) {
+    return request("/v3/ipgeo-bulk", {
+        lang: params.lang,
+        include: params.include,
+        fields: params.fields,
+        excludes: params.excludes,
+    }, { method: "POST", body: { ips: params.ips } });
+}
+export async function getAbuseContact(params) {
+    return request("/v3/abuse", {
+        ip: params.ip,
+        fields: params.fields,
+        excludes: params.excludes,
+    });
+}
+export async function parseUserAgent(params) {
+    return request("/v3/user-agent", {}, { method: "POST", body: { uaString: params.uaString } });
+}
+export async function parseUserAgentBulk(params) {
+    return request("/v3/user-agent-bulk", {}, { method: "POST", body: { uaStrings: params.uaStrings } });
+}
+export async function getAstronomyTimeSeries(params) {
+    return request("/v3/astronomy/timeSeries", {
+        lat: params.lat,
+        long: params.long,
+        location: params.location,
+        ip: params.ip,
+        dateStart: params.dateStart,
+        dateEnd: params.dateEnd,
+        elevation: params.elevation,
+        time_zone: params.time_zone,
+        lang: params.lang,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerGeolocationTools } from "./tools/geolocation.js";
+import { registerSecurityTools } from "./tools/security.js";
+import { registerTimezoneTools } from "./tools/timezone.js";
+import { registerAstronomyTools } from "./tools/astronomy.js";
+import { registerAsnTools } from "./tools/asn.js";
+import { registerAbuseTools } from "./tools/abuse.js";
+import { registerUserAgentTools } from "./tools/useragent.js";
+const server = new McpServer({
+    name: "ipgeolocation-io-mcp",
+    version: "1.0.0",
+});
+registerGeolocationTools(server);
+registerSecurityTools(server);
+registerTimezoneTools(server);
+registerAstronomyTools(server);
+registerAsnTools(server);
+registerAbuseTools(server);
+registerUserAgentTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    await server.close();
+    process.exit(0);
+});

package/dist/tools/abuse.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAbuseTools(server: McpServer): void;

package/dist/tools/abuse.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { getAbuseContact } from "../client.js";
+export function registerAbuseTools(server) {
+    server.registerTool("get_abuse_contact", {
+        title: "Abuse Contact Lookup",
+        annotations: {
+            readOnlyHint: true,
+        },
+        description: `Get abuse contact information for any IP address using ipgeolocation.io's dedicated abuse endpoint (GET /v3/abuse). Paid plans only. Free plan returns 401 Unauthorized. Costs 1 credit per lookup.
+
+Returns: route, country, name, organization, kind, address, emails (array), phone_numbers (array). Useful for reporting malicious activity to the correct network operator.
+
+Note: abuse data is also available through lookup_ip with include=abuse, which costs 2 credits total (1 base + 1 for abuse) but also returns full geolocation data. If you only need the abuse contact without geolocation, this dedicated endpoint is cheaper at 1 credit. Tip: you can also use lookup_ip with include=abuse&fields=abuse to get just the abuse data for 1 credit total. The fields and excludes parameters work on all plans to filter the response.`,
+        inputSchema: {
+            ip: z
+                .string()
+                .optional()
+                .describe("IPv4 or IPv6 address to get abuse contact for. Omit to use the caller's IP."),
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated fields to return (e.g. emails,organization). Reduces response size. Works on all plans."),
+            excludes: z
+                .string()
+                .optional()
+                .describe("Comma-separated fields to exclude from response (e.g. phone_numbers,address)."),
+        },
+    }, async (params) => {
+        try {
+            const result = await getAbuseContact(params);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/asn.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAsnTools(server: McpServer): void;

package/dist/tools/asn.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { getAsn } from "../client.js";
+export function registerAsnTools(server) {
+    server.registerTool("lookup_asn", {
+        title: "ASN Details",
+        annotations: {
+            readOnlyHint: true,
+        },
+        description: `Look up detailed Autonomous System Number (ASN) information using ipgeolocation.io's dedicated ASN endpoint (GET /v3/asn). Paid plans only. Free plan returns 401 Unauthorized. Costs 1 credit per lookup.
+
+Query by AS number (e.g. AS13335) or by IP address to find its ASN. Returns: as_number, asn_name, organization, country, type (ISP/Business/Hosting/etc), domain, rir (ARIN/RIPE/APNIC/etc), date_allocated, allocation_status, num_of_ipv4_routes, num_of_ipv6_routes.
+
+Optional include parameter adds: peers (peer ASNs), downstreams (downstream ASNs), upstreams (upstream ASNs), routes (announced IPv4/IPv6 routes), whois_response (raw WHOIS text).
+
+Note: basic ASN data (as_number, organization, country) is already included in lookup_ip responses on all plans including free. Paid plan lookup_ip also returns type, domain, date_allocated, and rir. This dedicated endpoint adds asn_name, allocation_status, route counts, and the optional peers/downstreams/upstreams/routes/whois data that lookup_ip does not provide. Use lookup_ip for basic ASN info. Use this tool only when you need the extended ASN details.`,
+        inputSchema: {
+            asn: z
+                .string()
+                .optional()
+                .describe("AS number to look up (e.g. AS13335 or just 13335). Takes priority over ip if both are provided."),
+            ip: z
+                .string()
+                .optional()
+                .describe("IPv4 or IPv6 address to find the ASN for. Used only if asn is not provided."),
+            include: z
+                .string()
+                .optional()
+                .describe("Comma-separated extra data to include: peers, downstreams, upstreams, routes, whois_response. No additional credit cost."),
+            fields: z
+                .string()
+                .optional()
+                .describe("Comma-separated dot-path fields to return (e.g. asn.as_number,asn.organization). Overrides include if both are set."),
+            excludes: z
+                .string()
+                .optional()
+                .describe("Comma-separated dot-path fields to exclude (e.g. asn.date_allocated,asn.rir)."),
+        },
+    }, async (params) => {
+        try {
+            const result = await getAsn(params);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/astronomy.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAstronomyTools(server: McpServer): void;

package/dist/tools/astronomy.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { getAstronomy, getAstronomyTimeSeries } from "../client.js";
+export function registerAstronomyTools(server) {
+    server.registerTool("get_astronomy", {
+        title: "Astronomy Data",
+        annotations: {
+            readOnlyHint: true,
+        },
+        description: `Get sunrise, sunset, moonrise, moonset, twilight times, golden hour, blue hour, sun/moon positions, and moon phase data for any location using ipgeolocation.io (GET /v3/astronomy). Works on all plans including free. Costs 1 credit per request.
+
+Look up by coordinates, city/address, or IP address. All lookup modes work on both free and paid plans. Supports custom dates and elevation for precise calculations.
+
+Returns: sunrise, sunset, solar_noon, day_length, moonrise, moonset, civil/nautical/astronomical twilight start and end times, golden_hour and blue_hour start and end, sun_altitude, sun_azimuth, sun_distance, moon_altitude, moon_azimuth, moon_distance, moon_parallactic_angle, moon_phase (name and value 0-1), moon_illumination percentage.
+
+The lang parameter for non-English location field responses is available on paid plans only. Free plan returns English responses regardless.`,
+        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 English."),
+        },
+    }, async (params) => {
+        try {
+            const result = await getAstronomy(params);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("get_astronomy_time_series", {
+        title: "Astronomy Time Series",
+        annotations: {
+            readOnlyHint: true,
+        },
+        description: `Get daily astronomical data for a date range (up to 90 days) using ipgeolocation.io's astronomy time series endpoint (GET /v3/astronomy/timeSeries). Works on all plans including free. Costs 1 credit per request regardless of the number of days.
+
+Returns an array of daily astronomy objects, one per day in the range. Each object includes: date, sunrise, sunset, solar_noon, day_length, moonrise, moonset, moon_phase, moon_illumination_percentage, and all twilight/golden hour/blue hour times.
+
+Time series responses do not include real-time positional data (sun_altitude, sun_azimuth, sun_distance, moon_altitude, moon_azimuth, moon_distance, moon_parallactic_angle). For those fields, use get_astronomy with a specific date instead.
+
+Location can be specified by coordinates, city/address, or IP. If no location is given, uses the caller's IP.`,
+        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."),
+            dateStart: z
+                .string()
+                .describe("Start date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days."),
+            dateEnd: z
+                .string()
+                .describe("End date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days."),
+            elevation: z
+                .string()
+                .optional()
+                .describe("Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations."),
+            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 languages."),
+        },
+    }, async (params) => {
+        try {
+            const result = await getAstronomyTimeSeries(params);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/geolocation.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGeolocationTools(server: McpServer): void;