IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/geolocation.ts:210-257 (registration)

  Registration of the "lookup_ip" tool using server.registerTool.

    server.registerTool(
      "lookup_ip",
      {
        title: "IP Geolocation Lookup",
        annotations: {
          readOnlyHint: true,
        },
        description: `Unified IP lookup via GET /v3/ipgeo. Cost: 1 credit. Use this first when one IP request needs multiple domains such as location, company/ASN, network, timezone, currency, security, or abuse.
  
  Free plan supports core location data, country metadata, currency, time_zone, basic ASN, and fields/excludes. Paid plan adds domain lookup, company, network, extended ASN, non-English lang, and include modules such as security or abuse. If fields reference an include-only module, this server infers the required include automatically.
  
  Omit ip to use the caller's IP. Use lookup_asn only for peers, upstreams, downstreams, routes, or WHOIS. Use check_security or get_abuse_contact only for single-domain lookups.`,
        inputSchema: {
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 address, IPv6 address, or domain name to look up. Domain lookups require a paid plan. Omit to use the caller's IP."
            ),
          lang: z
            .string()
            .optional()
            .describe(
              "Response language code (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt). Paid plans only. Free plan returns a 401 error if you pass any value other than en. Defaults to en."
            ),
          include: z
            .string()
            .optional()
            .describe(
              "Comma-separated extra modules to include in the response. Paid plans only. Options: security (+2 credits), abuse (+1 credit), hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or * for all (4 credits total). Free plan cannot use this parameter."
            ),
          fields: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to return (e.g. location.city,asn.organization). Works on all plans including free. Reduces response size and can reduce credit cost when combined with include. If a field references an include-only module (for example security.* or abuse.*), this server auto-adds the required include module."
            ),
          excludes: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to exclude from response (e.g. currency,location.continent_code). Works on all plans including free."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },

• src/tools/geolocation.ts:259-275 (handler)

  Handler implementation for "lookup_ip" tool, which processes parameters and calls fetching functions (getCachedOrFetchIpGeoInclude/Base).

  async (params) => {
    try {
      const effectiveInclude = mergeLookupIpInclude(
        params.include,
        params.fields
      );
      let result: unknown;
  
      if (effectiveInclude) {
        result = await getCachedOrFetchIpGeoInclude({
          include: effectiveInclude,
          ip: params.ip,
          lang: params.lang,
          fields: params.fields,
          excludes: params.excludes,
          forceRefresh: params.force_refresh,
        });