Have I Been Pwned MCP Server

Instructions

Implementation Reference

• src/index.ts:211-281 (handler)

  The primary handler function that executes the check_email tool logic, querying the HIBP API for breached accounts associated with the given email and formatting the response.
  private async handleCheckEmail(args: any) { if (!args.email || typeof args.email !== "string") { throw new McpError( ErrorCode.InvalidParams, "Email address is required" ); } const params: Record<string, any> = {}; if (args.include_unverified !== undefined) { params.includeUnverified = args.include_unverified; } if (args.truncate_response !== undefined) { params.truncateResponse = args.truncate_response; } const response = await this.axiosInstance.get(`/breachedaccount/${encodeURIComponent(args.email)}`, { params }); if (!response.data || response.data.length === 0) { return { content: [ { type: "text", text: "Good news! This email address has not been found in any known data breaches.", }, ], }; } // Format the breach data for better readability const breaches = response.data; const breachCount = breaches.length; let summary = `⚠️ This email address was found in ${breachCount} data breach${breachCount > 1 ? 'es' : ''}.\n\n`; if (args.truncate_response) { // If truncated, just list the breach names summary += "Breaches: " + breaches.map((breach: any) => breach.Name).join(", "); } else { // Otherwise, provide detailed information summary += "Breach details:\n\n"; breaches.forEach((breach: any, index: number) => { summary += `${index + 1}. ${breach.Name} (${breach.BreachDate})\n`; summary += ` Domain: ${breach.Domain}\n`; summary += ` Description: ${breach.Description}\n`; summary += ` Compromised data: ${breach.DataClasses.join(", ")}\n`; if (index < breaches.length - 1) { summary += "\n"; } }); summary += "\nRecommendations:\n"; summary += "- Change your password for these services immediately\n"; summary += "- If you used the same password elsewhere, change those too\n"; summary += "- Enable two-factor authentication where available\n"; summary += "- Consider using a password manager"; } return { content: [ { type: "text", text: summary, }, ], }; }
• src/index.ts:83-102 (schema)

  Input schema defining the parameters for the check_email tool, including email (required), include_unverified, and truncate_response options.
  inputSchema: { type: "object", properties: { email: { type: "string", description: "Email address to check", }, include_unverified: { type: "boolean", description: "Include unverified breaches in the results", default: true, }, truncate_response: { type: "boolean", description: "Truncate the response to only include breach names", default: false, }, }, required: ["email"], },
• src/index.ts:80-103 (registration)

  Registration of the check_email tool in the list of available tools returned by ListToolsRequestSchema.
  { name: "check_email", description: "Check if an email address has been found in data breaches", inputSchema: { type: "object", properties: { email: { type: "string", description: "Email address to check", }, include_unverified: { type: "boolean", description: "Include unverified breaches in the results", default: true, }, truncate_response: { type: "boolean", description: "Truncate the response to only include breach names", default: false, }, }, required: ["email"], }, },
• src/index.ts:165-166 (handler)

  Dispatch in the CallToolRequestSchema handler that routes check_email calls to the handleCheckEmail function.
  case "check_email": return await this.handleCheckEmail(request.params.arguments);
• src/index.ts:182-191 (helper)

  Special error handling for 404 responses specific to check_email, treating it as a successful 'no breaches found' result.
  if (error.response?.status === 404 && request.params.name === "check_email") { return { content: [ { type: "text", text: "Good news! This email address has not been found in any known data breaches.", }, ], }; }