Skip to main content
Glama
Usama015

whoismd-mcp-server

by Usama015
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

whoismd-mcp-server

M8ven Live Monitored

Listed on mcpservers.org

🛡️ Verified Agentic Trust: Vetted by M8ven with a 89/100 Trust Score for secure, sandbox-safe execution.

Open-source native MCP (Model Context Protocol) server driver for WhoisMD real-time internet intelligence routing. Give your AI agents the ability to run deep network forensics, verify domains, and analyze cyber threats natively inside your IDE.

🔑 Get Your API Key: This server acts as an unprivileged client driver. Every tool call is safely delegated to the public WhoisMD REST API (/v1/intel/lookup) and requires your own API credentials. Create an account on the WhoisMD Dashboard to get your pg_live_... API key.

🤖 How to Prompt Your AI Agent

Once configured, you don't need to write code. Just talk to your AI agent (Cursor, Windsurf, Claude) naturally:

  • "Check if this domain looks like a phishing variant of google.com using whoismd."

  • "Run a bulk infrastructure look up on these 10 domains to find their threat risk scores."

Related MCP server: dns-mcp

Tools

Tool

Description

whoismd_lookup

Full domain intelligence lookup — WHOIS/RDAP, DNS (A/AAAA/MX/NS/TXT), IP resolution, deterministic 0–100 threat risk score.

whoismd_bulk

Batch lookup of up to 100 domains with bounded concurrency (5).

Each lookup returns riskScore, riskLevel, aiCleanSummary, creditsSpent, creditsRemaining, and the full data report. Calls are credit-metered by the API key holder.

Requirements

  • Node.js >= 20 (native fetch required)

  • A WhoisMD API key (pg_live_...) — generate one from the WhoisMD dashboard after signup. Keys are scoped to the live_lookup tier and rate-limited to 20 requests/minute.

Running

Build & run directly

npm install
npm run build
WHOISMD_API_KEY=pg_live_... node dist/index.js

The server speaks MCP over stdio (JSON-RPC), so it must be launched by an MCP-capable client — not invoked interactively.

Development

npm run dev          # tsx watch, no build step
npm run typecheck    # tsc --noEmit

Environment variables

Variable

Default

Required

Description

WHOISMD_API_KEY

—

yes

Your pg_live_... API key. Never hard-code.

WHOISMD_API_BASE

https://whoismd.com/api

no

Overrides the API base URL (for testing).

Client configuration

Cursor

.cursor/mcp.json in your project (or the global Cursor MCP config):

{
  "mcpServers": {
    "whoismd": {
      "command": "npx",
      "args": ["-y", "whoismd-mcp-server"],
      "env": {
        "WHOISMD_API_KEY": "pg_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

To point at a local checkout instead:

{
  "mcpServers": {
    "whoismd": {
      "command": "node",
      "args": ["/absolute/path/to/whoismd-mcp-server/dist/index.js"],
      "env": {
        "WHOISMD_API_KEY": "pg_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Windsurf

Windsurf uses the same MCP JSON shape. Add it via ~/.codeium/windsurf/mcp_config.json, or through Settings → MCP → Add:

{
  "mcpServers": {
    "whoismd": {
      "command": "npx",
      "args": ["-y", "whoismd-mcp-server"],
      "env": {
        "WHOISMD_API_KEY": "pg_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "whoismd": {
      "command": "npx",
      "args": ["-y", "whoismd-mcp-server"],
      "env": {
        "WHOISMD_API_KEY": "pg_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Generic clients

npx -y whoismd-mcp-server
# or
node /absolute/path/to/whoismd-mcp-server/dist/index.js

The API key can also be exported in the environment of the client process instead of the config env block — how you inject it is up to your client's security model. Prefer config-injected env, never shell history or commit.

Security

  • The API key is consumed from the environment / client config only; it is never embedded, logged, or written to disk by this server.

  • All traffic goes to the public WhoisMD endpoint over HTTPS.

  • This driver is deliberately read-only and unprivileged: no private database, no reverse footprint history, no admin surface.

License

MIT

Available Tools

2 tools
whoismd_bulkA

Run batch domain intelligence lookups for up to 100 distinct domains via the public WhoisMD API. Each entry is analyzed concurrently with bounded parallelism. Returns per-domain success/failure results with risk scores.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainsYesArray of domain names to analyze in batch

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses concurrent analysis with bounded parallelism and per-domain success/failure results, but omits auth requirements, rate limits, error handling, and whether failed domains can be retried independently.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with purpose, then execution behavior, then return shape. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter batch lookup with no output schema, the description covers the core operation, concurrency model, and return format including risk scores. It is nearly complete, though it could clarify risk-score semantics and any public API limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines the domains array. The description still adds semantic value by specifying 'distinct' domains and reinforcing the 100-item cap, which the schema's maxItems states but the schema description does not call out as a uniqueness requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: batch domain intelligence lookups, scoped to up to 100 distinct domains via the public WhoisMD API. The word 'batch' and the limit clearly distinguish it from the single-domain sibling whoismd_lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The batch context and 100-domain limit imply this tool is for multiple domains rather than single lookups, but it never explicitly says when to prefer it over whoismd_lookup or when not to use it. Usage is inferable but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoismd_lookupA

Perform a full domain intelligence lookup against the public WhoisMD API: WHOIS/RDAP registration data, DNS records (A, AAAA, MX, NS, TXT), SSRF-safe IP resolution, and a deterministic 0-100 threat risk score. Returns a comprehensive JSON report.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesThe domain name to analyze (e.g. 'example.com')

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does add useful traits: it identifies the API as public (implying no auth), notes SSRF-safe IP resolution, and states the risk score is deterministic (0-100). However, it says nothing about rate limits, error behavior, or cost, which are relevant for an external API call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences that front-load the core purpose and then enumerate the return payload. Dense but no filler; the enumeration of DNS record types is arguably more detail than an agent needs to select the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter lookup tool with no output schema, the description adequately conveys what data comes back (registration, DNS, IP, risk score) and that the response is JSON. It omits the response shape, but given the tool's simplicity and that no output schema exists to defer to, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter exists and schema description coverage is 100%, so the schema already documents it fully (including the example and length bounds). The description adds no parameter-specific syntax beyond what is structured. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Perform a full domain intelligence lookup") and enumerates the exact data categories returned (WHOIS/RDAP, DNS records, IP resolution, risk score). It does not explicitly contrast itself with the sibling whoismd_bulk, though the singular "lookup" vs "bulk" naming implies the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The scope is implied to be single-domain analysis via the required domain parameter, and the sibling name (whoismd_bulk) hints at the batch alternative, but the description never states when to use this tool versus the bulk variant or any preconditions. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedwhoismd_bulk
    • First observedwhoismd_lookup
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one handles a single domain lookup, the other handles batch processing of many domains. There is no ambiguity in their purposes.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern using snake_case with the same whoismd_ prefix: whoismd_lookup and whoismd_bulk. The naming is predictable and uniform.

Tool Count3/5

With only two tools, the server is quite thin for a domain intelligence service. While each tool is useful, the absence of operations like historical data, reverse WHOIS, or alerting makes the count feel borderline minimal.

Completeness3/5

The server covers basic single and bulk lookups, but lacks other common domain intelligence operations such as historical WHOIS, reverse IP lookups, or real-time monitoring. These gaps may limit its usefulness for advanced workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-server-dns

    ofershap
    A
    license
    A
    quality
    D
    maintenance
    MCP server for DNS lookups, reverse DNS, WHOIS, and domain checks. Zero auth, zero config.
    5
    32 npm
    3
    MIT

  • domainintel-mcp

    Bishop81
    A
    license
    A
    quality
    C
    maintenance
    An MCP server for domain intelligence — WHOIS, DNS records, SSL certificate inspection, SPF/DMARC validation, security-header audits, and blacklist/reputation checks, callable by AI agents. Powered by domainintel.app; runs server-side, no local setup.
    7
    46 npm
    MIT