IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/geolocation.ts:406-451 (handler)

  The implementation of the lookup_company tool, including registration and the async handler function that fetches IP geolocation data restricted to company and ASN fields.

    server.registerTool(
      "lookup_company",
      {
        title: "Company/Organization Lookup",
        annotations: {
          readOnlyHint: true,
        },
        description: `Decision policy: this is a single-domain tool. Use it only when the user asks for ownership data (company/ASN) only. If the same IP request also needs security, abuse, location/city, timezone, network, or currency data, call lookup_ip once with include and targeted fields/excludes instead of chaining tools.
  
  Ownership lookup via GET /v3/ipgeo with company and ASN only. Paid only. Cost: 1 credit. Returns the company using the IP and the ASN holder routing it.
  
  Tool selection rule: if this tool is used, call it once per IP target and post-process locally. Do not re-call lookup_company for the same IP just to change output shape.`,
        inputSchema: {
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 or IPv6 address to look up. Omit to check the caller's IP."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },
      },
      async (params) => {
        try {
          const baseResult = await getCachedOrFetchIpGeoBase({
            ip: params.ip,
            forceRefresh: params.force_refresh,
          });
  
          const result = applyFieldsAndExcludes(baseResult, {
            fields: "company,asn",
          });
  
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );