---
name: hibp-mcp
description: >
  Use the Have I Been Pwned MCP server to check data breaches, password prevalence, paste
  exposure, and domain monitoring. Load when an email address, password, or domain needs
  to be checked against known data breaches or stealer logs.
---

# Have I Been Pwned MCP Server

**MCP URL:** `https://haveibeenpwned.com/mcp`  
**Transport:** Streamable HTTP (`POST`)

## Quick Setup

Use OAuth discovery for authenticated MCP tools:

1. Discover the protected resource metadata at `https://haveibeenpwned.com/.well-known/oauth-protected-resource`
2. Follow `https://haveibeenpwned.com/auth.md` to register a public OAuth client and complete Authorization Code + PKCE
3. Call `https://haveibeenpwned.com/mcp` with `Authorization: Bearer <access_token>` for authenticated tool calls

Public breach catalogue, data class, and Pwned Passwords tools work without auth.  
Account, domain, stealer-log, and subscription tools require an OAuth access token linked to an active HIBP subscription.

---

## Public Tools (no auth required)

| Tool | What it does |
|------|-------------|
| `hibp_list_breaches` | List all public breaches; filter by domain, spam-list flag, or verification status |
| `hibp_get_breach` | Get full details for a single breach by name |
| `hibp_get_latest_breach` | Return the most recently added public breach |
| `hibp_list_data_classes` | List all data classes that appear in HIBP breach records |
| `hibp_get_pwned_passwords_range` | k-anonymity password check — send a 5-char SHA-1 or NTLM prefix, receive matching hash suffixes with exposure counts |

---

## Authenticated Tools (require OAuth bearer token)

### Account & paste lookup
| Tool | What it does |
|------|-------------|
| `hibp_get_breached_account` | All breaches affecting an email address |
| `hibp_get_breached_account_range` | k-anonymity account range search (SHA-1 prefix of email) |
| `hibp_get_paste_account` | All paste-site exposures for an email address |

### Domain monitoring
| Tool | What it does |
|------|-------------|
| `hibp_get_breached_domain` | All breaches affecting a monitored domain |
| `hibp_list_subscribed_domains` | Domains currently in the account's subscription |
| `hibp_get_subscription_status` | Current subscription plan, rate limits, and access tier |

### Stealer logs
| Tool | What it does |
|------|-------------|
| `hibp_get_stealer_logs_by_email` | Stealer-log records tied to an email address |
| `hibp_get_stealer_logs_by_website_domain` | Stealer logs for credentials from a website domain |
| `hibp_get_stealer_logs_by_email_domain` | Stealer logs for all emails under an email domain |

### Domain verification
| Tool | What it does |
|------|-------------|
| `hibp_generate_domain_verification_dns_token` | Generate a TXT record value for DNS-based domain verification |
| `hibp_verify_domain_verification_dns_token` | Confirm DNS record has propagated and verify the domain |
| `hibp_send_domain_verification_email` | Send an approval email to a standard alias for email-based verification |

---

## Resources

These resources provide catalogue-style data without requiring tool parameters:

| URI | Contents |
|-----|----------|
| `hibp://breaches/catalogue` | Full list of all breaches (JSON) |
| `hibp://breaches/latest` | Most recently added breach (JSON) |
| `hibp://breaches/by-name/{name}` | Single breach by name (template) |
| `hibp://dataclasses` | All data classes (JSON) |
| `hibp://guides/server` | Capability overview and composition guidance |
| `hibp://guides/test-accounts` | Integration-test email aliases with documented behaviors |
| `hibp://guides/domain-verification` | Step-by-step DNS and email verification workflows |

---

## Prompts

| Prompt | What it does |
|--------|-------------|
| `hibp-account-triage` | Guided investigation of a potentially breached email address |
| `hibp-domain-verification-workflow` | Step-by-step domain verification via DNS or email |

---

## Usage Guidance

- **Password check:** Hash the password with SHA-1, take the first 5 characters (uppercase hex), call `hibp_get_pwned_passwords_range`. Check if the remaining suffix appears in the result — if count > 0, the password has been exposed.
- **Account triage:** Call `hibp_get_breached_account` and `hibp_get_paste_account` together to get the full picture for an email address. Use the `hibp-account-triage` prompt to automate this.
- **Breach research:** Use `hibp_list_breaches` with domain filter, or read the `hibp://breaches/catalogue` resource for bulk exploration. Call `hibp_get_breach` for full details on a specific incident.
- **Stealer logs:** Require an OAuth connection backed by a subscription with stealer-log access. Call `hibp_get_stealer_logs_by_email` first; use domain variants for bulk org-level checks.
- **Domain verification:** Read `hibp://guides/domain-verification` before starting, then follow the DNS or email workflow tools.

---

## Response Format

All tools accept an optional `response_format` parameter:
- `"markdown"` (default) — human-readable formatted output
- `"json"` — structured data for programmatic processing

## Rate Limits & Errors

- `401` — missing or invalid OAuth bearer token. Restart from `/.well-known/oauth-protected-resource` and `auth.md` to obtain a fresh token.
- `429` — rate limited. The response includes `retryAfterSeconds` and `rateLimitResetAt`. Honor the retry window before calling again.
- `403` — the linked HIBP subscription does not have access to this specific tool tier (e.g., stealer logs require a higher plan).