IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/geolocation.ts:499-541 (handler)

  The tool 'lookup_network' is registered in 'src/tools/geolocation.ts'. The handler executes 'getCachedOrFetchIpGeoBase' and then applies projection to return only the 'network' field.

      "lookup_network",
      {
        title: "Network/Routing Info",
        annotations: {
          readOnlyHint: true,
        },
        description: `Network lookup via GET /v3/ipgeo with network only. Paid only. Cost: 1 credit. Returns route prefix, connection type, and anycast status.
  
  Tool selection rule: use this tool for network-only requests. If the request also needs other IP domains, prefer one lookup_ip call with include plus targeted fields/excludes.`,
        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: "network",
          });
  
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );