OSINT MCP Server

Implementation Reference

• src/index.ts:183-192 (handler)

  Tool registration and wrapper handler for shodan_host.

  server.tool(
    "shodan_host",
    { ip: z.string().describe("IP address to lookup in Shodan") },
    async ({ ip }) => {
      const result = await shodanClient.getHost(ip);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/tools/shodan.ts:14-38 (handler)

  Actual API implementation logic for fetching host data from Shodan.

  async getHost(ip: string): Promise<ShodanHost> {
    const apiKey = configManager.get("SHODAN_API_KEY");
    if (!apiKey) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "SHODAN_API_KEY is not configured"
      );
    }
  
    try {
      const data = await this.fetch<any>(`shodan/host/${ip}`, {
        method: "GET",
      }, {
        key: apiKey,
      });
  
      return ShodanHostSchema.parse(data);
    } catch (error) {
      if (error instanceof McpError) throw error;
      throw new McpError(
        ErrorCode.InternalError,
        `Shodan error: ${(error as Error).message}`
      );
    }
  }

• src/types/index.ts:75-88 (schema)

  Zod schema validation and type definition for Shodan host response.

  export const ShodanHostSchema = z.object({
    ip_str: z.string(),
    port: z.number(),
    transport: z.string(),
    hostnames: z.array(z.string()),
    location: z.any(),
    org: z.string().optional(),
    isp: z.string().optional(),
    asn: z.string().optional(),
    os: z.string().optional(),
    domains: z.array(z.string()),
    data: z.array(z.any()),
  });