OSINT MCP Server

Implementation Reference

• src/tools/ip-geolocation.ts:13-53 (handler)

  The `getLocation` method in `IpApiClient` fetches and returns the IP geolocation data.

  async getLocation(ip: string): Promise<IpGeolocation> {
    try {
      const data = await this.fetch<any>(ip, {
        method: "GET",
      }, {
        fields: "status,message,country,countryCode,region,regionName,city,zip,lat,lon,timezone,isp,org,as,mobile,proxy,hosting,query"
      });
  
      if (data.status === "fail") {
        throw new McpError(
          ErrorCode.InvalidRequest,
          `IP Geolocation failed: ${data.message}`
        );
      }
  
      return IpGeolocationSchema.parse({
        ip: data.query,
        country: data.country,
        countryCode: data.countryCode,
        region: data.region,
        regionName: data.regionName,
        city: data.city,
        zip: data.zip,
        lat: data.lat,
        lon: data.lon,
        timezone: data.timezone,
        isp: data.isp,
        org: data.org,
        as: data.as,
        mobile: data.mobile,
        proxy: data.proxy,
        hosting: data.hosting,
      });
    } catch (error) {
      if (error instanceof McpError) throw error;
      throw new McpError(
        ErrorCode.InternalError,
        `IP Geolocation error: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:99-108 (registration)

  The `ip_geolocation` tool is registered using the `server.tool` method, which calls the `ipClient.getLocation` handler.

  server.tool(
    "ip_geolocation",
    { ip: z.string().describe("IP address to geolocate") },
    async ({ ip }) => {
      const result = await ipClient.getLocation(ip);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/types/index.ts:4-23 (schema)

  Zod schema defining the structure of the IP geolocation result.

  export const IpGeolocationSchema = z.object({
    ip: z.string(),
    country: z.string().optional(),
    countryCode: z.string().optional(),
    region: z.string().optional(),
    regionName: z.string().optional(),
    city: z.string().optional(),
    zip: z.string().optional(),
    lat: z.number().optional(),
    lon: z.number().optional(),
    timezone: z.string().optional(),
    isp: z.string().optional(),
    org: z.string().optional(),
    as: z.string().optional(),
    mobile: z.boolean().optional(),
    proxy: z.boolean().optional(),
    hosting: z.boolean().optional(),
  });
  
  export type IpGeolocation = z.infer<typeof IpGeolocationSchema>;