Credential Check MCP Server

A comprehensive credential security and breach detection service using the HaveIBeenPwned (HIBP) API and privacy-preserving k-anonymity protocols. This MCP (Model Context Protocol) server enables Claude to check email addresses against known data breaches, verify password security without transmitting passwords, identify hash algorithms, validate password policies, and analyze breach statistics for domains.

Overview

This server provides access to credential security intelligence through a unified interface:

• HaveIBeenPwned Email Breach API - Check if email addresses have been exposed in known data breaches
• HaveIBeenPwned Pwned Passwords API - Verify password compromise status using k-anonymity (passwords never transmitted)
• Hash Algorithm Identification - Detect hash algorithms from hash strings
• Password Policy Validation - Evaluate passwords against configurable security requirements
• Breach Statistics - Aggregate breach analysis and timeline data for domains

Perfect for security audits, credential validation, password security assessment, and breach impact analysis.

Tools

| Tool | API | Description | |------|-----|-------------| | hibp_email | HaveIBeenPwned | Check if email address appears in known data breaches | | hibp_password | HaveIBeenPwned | Check if password is compromised using k-anonymity (password never sent to API) | | hibp_domain | HaveIBeenPwned | Search for all breaches affecting a specific domain | | hash_identify | Local | Identify hash algorithm from hash string | | password_policy_check | Local | Validate password against configurable security policy | | credential_stats | HaveIBeenPwned | Get breach statistics and timeline for a domain |

HaveIBeenPwned Email Breach Check

Check if an email address has been found in known data breaches.

Input Parameters:

{
  email: string  // Email address to check (must be valid email format)
}

Example Request:

{
  "email": "[email protected]"
}

Example Output:

{
  "email": "[email protected]",
  "total_breaches": 2,
  "breaches": [
    {
      "Name": "Adobe",
      "Domain": "adobe.com",
      "BreachDate": "2013-10-04",
      "DataClasses": ["Email addresses", "Passwords"],
      "IsVerified": true,
      "IsFabricated": false,
      "Description": "Adobe account data was breached.",
      "PwnCount": 153445215
    },
    {
      "Name": "Equifax",
      "Domain": "equifax.com",
      "BreachDate": "2017-09-15",
      "DataClasses": ["Names", "Email addresses", "Social security numbers"],
      "IsVerified": true,
      "IsFabricated": false,
      "Description": "Equifax was breached exposing personal information.",
      "PwnCount": 147000000
    }
  ],
  "message": "Email found in breaches"
}

HaveIBeenPwned Password Check

Check if a password has been compromised using k-anonymity. The password is hashed locally and never sent to the API in full form.

Input Parameters:

{
  password: string  // Password to check (hashed locally, never transmitted in full)
}

Example Request:

{
  "password": "MySecurePassword123!"
}

Example Output:

{
  "is_compromised": false,
  "times_seen": 0,
  "message": "This password has not been found in known data breaches"
}

Alternative output when password is compromised:

{
  "is_compromised": true,
  "times_seen": 45382,
  "message": "WARNING: This password has been seen 45382 times in data breaches"
}

HaveIBeenPwned Domain Breach Search

Search for all breaches affecting a specific domain.

Input Parameters:

{
  domain: string  // Domain name to search (e.g., example.com)
}

Example Request:

{
  "domain": "example.com"
}

Example Output:

{
  "domain": "example.com",
  "total_breaches": 1,
  "breaches": [
    {
      "Name": "Example Breach",
      "Domain": "example.com",
      "BreachDate": "2015-03-20",
      "DataClasses": ["Email addresses", "Passwords", "Names"],
      "IsVerified": true,
      "IsFabricated": false,
      "Description": "Data from Example Corporation servers was accessed.",
      "PwnCount": 95000
    }
  ]
}

Hash Algorithm Identification

Identify the hash algorithm used on a hash string by analyzing its format and length.

Input Parameters:

{
  hash_string: string  // Hash string to identify
}

Example Request (MD5 hash):

{
  "hash_string": "5d41402abc4b2a76b9719d911017c592"
}

Example Output (MD5):

{
  "hash_string": "5d41402abc4b2a7...",
  "hash_length": 32,
  "possible_algorithms": [
    {
      "name": "MD5",
      "confidence": "high"
    }
  ]
}

Example Request (bcrypt hash):

{
  "hash_string": "$2b$12$eImiTXuWVxfaHNYY0iNAfeHjWqcvV3PH5xGVhW9rvKJVHvgq5pPNm"
}

Example Output (bcrypt):

{
  "hash_string": "$2b$12$eImiTXuWVxfaHN...",
  "hash_length": 60,
  "possible_algorithms": [
    {
      "name": "bcrypt",
      "confidence": "high"
    }
  ]
}

Supported algorithms:

• MD5 (32 characters)
• SHA1 (40 characters)
• SHA224 (56 characters)
• SHA256 (64 characters)
• SHA384 (96 characters)
• SHA512 (128 characters)
• bcrypt ($2a$, $2b$)
• Argon2 ($argon2...)
• SHA256crypt ($5$)
• SHA512crypt ($6$)
• MD5crypt ($1$)

Password Policy Check

Validate a password against configurable security policy requirements.

Input Parameters:

{
  password: string,  // Password to check
  policy: {
    min_length: number,         // Minimum length (default: 8)
    max_length: number,         // Maximum length (optional)
    require_uppercase: boolean, // Require uppercase letters (default: true)
    require_lowercase: boolean, // Require lowercase letters (default: true)
    require_numbers: boolean,   // Require digits (default: true)
    require_special: boolean    // Require special characters (default: true)
  }  // Policy object (optional, uses defaults if omitted)
}

Example Request (default policy):

{
  "password": "MyPassword123!"
}

Example Output (passes policy):

{
  "passes": true,
  "strength_score": 100,
  "failures": [],
  "policy_applied": {
    "min_length": 8,
    "max_length": null,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_special": true
  }
}

Example Request (custom policy):

{
  "password": "password123",
  "policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_special": false
  }
}

Example Output (fails policy):

{
  "passes": false,
  "strength_score": 80,
  "failures": [
    "Password must be at least 12 characters"
  ],
  "policy_applied": {
    "min_length": 12,
    "max_length": null,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_special": false
  }
}

Credential Statistics

Get comprehensive breach statistics for a domain including total breaches, accounts affected, data classes exposed, and breach timeline.

Input Parameters:

{
  domain: string  // Domain to analyze (e.g., example.com)
}

Example Request:

{
  "domain": "example.com"
}

Example Output (domain with breaches):

{
  "domain": "example.com",
  "total_breaches": 2,
  "total_accounts_affected": 15000000,
  "data_classes_exposed": [
    "Email addresses",
    "Financial information",
    "Names",
    "Passwords"
  ],
  "most_recent_breach": {
    "name": "Example Data Leak",
    "date": "2020-06-15",
    "accounts_affected": 5000000,
    "data_classes": ["Email addresses", "Names"]
  },
  "breach_timeline": [
    {
      "date": "2020-06-15",
      "name": "Example Data Leak",
      "accounts_affected": 5000000,
      "is_verified": true
    },
    {
      "date": "2015-03-20",
      "name": "Example Breach",
      "accounts_affected": 10000000,
      "is_verified": true
    }
  ]
}

Example Output (domain with no breaches):

{
  "domain": "safe-domain.com",
  "total_breaches": 0,
  "total_accounts_affected": 0,
  "data_classes_exposed": [],
  "most_recent_breach": null,
  "breach_timeline": []
}

Configuration

Environment Variables

This server requires an API key for email breach checks. Password checks do NOT require authentication as they use the public k-anonymity API. Set this environment variable before running:

export HIBP_API_KEY="your-haveibeenpwned-api-key"

Getting API Keys

HaveIBeenPwned Email Breach API

• Register at https://haveibeenpwned.com/API/Key
• Email address verification required
• Free tier provides access to the email breach API
• Rate limit: Depends on subscription level
• Documentation: https://haveibeenpwned.com/API/v3

Password Checks (Public API)

• No API key required for password checks
• Uses HaveIBeenPwned's public k-anonymity API endpoint
• Rate limit: Reasonable limits (not documented)
• Documentation: https://haveibeenpwned.com/API/v3#PwnedPasswords

Rate Limits Summary

| Service | Tier | Rate Limit | |---------|------|-----------| | HIBP Email Breach API | Free | Per-domain subscription | | HIBP Password API | Public | Reasonable limits |

Installation

Prerequisites

• Bun runtime (version 1.x or later)
• Node.js 18+ (alternative runtime)
• Optional: Valid HIBP API key for email breach checks (password checks work without a key)

Steps

1. Clone or download this repository:

git clone <repo-url>
cd credential-check

2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Set environment variables (optional for password checks):

export HIBP_API_KEY="your-haveibeenpwned-api-key"

5. Run the server:

bun run start

The server will start listening on stdio transport.

Usage

Running the Server

Start the server with Bun:

bun run src/index.ts

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "credential-check": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/credential-check/src/index.ts"
      ],
      "env": {
        "HIBP_API_KEY": "your-haveibeenpwned-api-key"
      }
    }
  }
}

Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in .mcp.json or via settings UI):

{
  "servers": {
    "credential-check": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/credential-check/src/index.ts"],
      "env": {
        "HIBP_API_KEY": "your-haveibeenpwned-api-key"
      }
    }
  }
}

Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

Request: "Check if [email protected] has been in any data breaches"

Claude will call:

{
  "tool": "hibp_email",
  "input": {
    "email": "[email protected]"
  }
}

Request: "Is the password 'MyPassword123!' safe and does it meet standard security requirements?"

Claude will call:

{
  "tool": "hibp_password",
  "input": {
    "password": "MyPassword123!"
  }
}

Then optionally:

{
  "tool": "password_policy_check",
  "input": {
    "password": "MyPassword123!"
  }
}

Request: "What hash algorithm is 5d41402abc4b2a76b9719d911017c592?"

Claude will call:

{
  "tool": "hash_identify",
  "input": {
    "hash_string": "5d41402abc4b2a76b9719d911017c592"
  }
}

Request: "Show me breach statistics for example.com including timeline and exposed data"

Claude will call:

{
  "tool": "credential_stats",
  "input": {
    "domain": "example.com"
  }
}

Security

This server implements comprehensive input validation and security measures to protect user privacy and prevent misuse:

Password Privacy - K-Anonymity Protocol

The server uses HaveIBeenPwned's industry-standard k-anonymity protocol for password checking:

• Local hashing: Passwords are hashed locally using SHA1
• Prefix transmission: Only the first 5 characters of the SHA1 hash are sent to the HIBP API
• Full password never transmitted: The complete password and full hash never leave the local client
• Privacy preserved: HIBP receives a partial hash that provides no information about the actual password
• No logging: Passwords are never logged, stored, or cached on any system

This approach ensures that HaveIBeenPwned cannot determine which password is being checked, while still allowing the server to verify whether the password appears in breach databases.

Input Validation

Email Validation

• Requires valid RFC-compliant email format
• Standard email format checking
• Rejects malformed addresses

Domain Validation

• Validates RFC-compliant domain format
• Requires at least one dot and valid TLD
• Maximum length: 253 characters
• Rejects invalid characters

Hash String Validation

• Accepts only hexadecimal characters (0-9, a-f, A-F)
• Validates against known hash lengths (32, 40, 56, 64, 96, 128 characters for common algorithms)
• Supports special format hashes (bcrypt, Argon2, crypt variants)
• Maximum length: 128 characters

Password Validation

• Accepts passwords up to 200 characters
• No character restrictions (supports all Unicode characters for global users)
• Processed locally only

What Gets Blocked

The server rejects:

• Invalid email formats
• Malformed domain names
• Non-hexadecimal hash strings with invalid lengths
• Oversized inputs beyond limits
• Missing required API keys (for email breach checks)

Error Handling

• Invalid inputs return descriptive error messages
• API errors are caught and reported with status codes
• Missing API keys trigger helpful configuration messages
• Network timeouts are handled gracefully

License

ISC License - see LICENSE file for details