openlookup-mcp

An MCP (Model Context Protocol) server for OpenLookup.io, the email, phone, IP, and domain risk intelligence API. Point a coding agent (Claude Code, Claude Desktop, Cursor, or any other MCP client) at this server and it can score any of the four and wire OpenLookup into your codebase directly, without you copy-pasting curl commands from the docs.

Tools

Each product gets a single-item and a batch tool (batch scores sequentially, up to 25 per call):

• check_email / check_emails_batch: email risk score, classification, recommendation, and signals (syntax, domain/MX, disposable, role account, free provider).
• check_phone / check_phones_batch: phone risk score via real numbering-plan data (syntax, country, line type - mobile, VOIP, premium-rate, etc.).
• check_ip / check_ips_batch: IP risk score (format, private-range, datacenter/VPN heuristic).
• check_domain / check_domains_batch: domain risk score via live RDAP + TLS handshake (age, SPF/DMARC/DKIM, certificate validity).
• get_api_overview: a short reference for all four endpoints (auth, request/response shape), so an agent can generate integration code without fetching the web docs.

Every result shares the same shape: a 0-100 risk_score, a classification, a recommendation, and a product-specific signals object. A signal the API can't determine yet (e.g. phone reachable, IP country) comes back null rather than guessed, and is never penalized.

Full API reference: https://openlookup.io/docs.

Setup

You'll want an API key from your OpenLookup dashboard for production use. Without one, requests are anonymous, rate-limited, and don't consume credits, fine for trying this out.

Claude Code

claude mcp add openlookup -- npx -y openlookup-mcp

Or with an API key:

claude mcp add openlookup -e OPENLOOKUP_API_KEY=ol_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx -- npx -y openlookup-mcp

Claude Desktop / other MCP clients

Add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "openlookup": {
      "command": "npx",
      "args": ["-y", "openlookup-mcp"],
      "env": {
        "OPENLOOKUP_API_KEY": "ol_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | | ---------------------- | -------- | -------------------------------------------------------------------- | | OPENLOOKUP_API_KEY | No | Your OpenLookup API key. Omit for anonymous, rate-limited requests. | | OPENLOOKUP_BASE_URL | No | Overrides the API base URL. Defaults to https://openlookup.io/api. |

Development

npm install
npm run test        # vitest, includes an in-process MCP client/server round trip
npm run typecheck
npm run build        # compiles src/ to dist/
node scripts/smoke-test.mjs   # spawns the built server over real stdio and calls it

src/client.ts is a small dependency-injected HTTP client (an injectable fetchImpl, no env reads inside it) so it's testable without a live API. src/server.ts builds the MCP server and registers tools against that client; src/index.ts is the thin stdio entrypoint that reads env vars and wires the two together. src/server.test.ts tests the server the way the SDK recommends: a real Client and Server connected over InMemoryTransport, not raw handler calls.

License

MIT