@numradar/mcp

Check whether phone numbers are registered on WhatsApp, from your AI agent.

numradar answers one question well: is this number on WhatsApp? This is its Model Context Protocol server, so an agent can ask that question directly — validating a list, auditing contacts before a campaign, or checking a balance before spending it.

npx @numradar/mcp --token nr_live_YOUR_KEY

Create a key at numradar.app/app/keys.

---

Most people should not install anything

numradar runs a hosted MCP server. No package, no local process, no version to go stale on anyone's laptop:

https://numradar.app/mcp

Point your client at that URL with an Authorization: Bearer nr_live_... header and you are done.

{
  "mcpServers": {
    "numradar": {
      "type": "http",
      "url": "https://numradar.app/mcp",
      "headers": {
        "Authorization": "Bearer nr_live_xxx"
      }
    }
  }
}

The npm package exists for one real case: clients whose config file accepts a command to spawn but not a URL. claude_desktop_config.json is the common one. If you are editing a file like that, you need the package:

{
  "mcpServers": {
    "numradar": {
      "command": "npx",
      "args": ["-y", "@numradar/mcp", "--token", "nr_live_xxx"]
    }
  }
}

Configuration for 15 verified clients — Claude Code, Cursor, Windsurf, Zed, VS Code, Cline and the rest — is at numradar.app/mcp-server.

Tools

Tool	What it does	Cost
validate_number	One number. Registered or not, business account, line type, country.	1 credit
bulk_validate	Up to 10,000 numbers. Returns a job id immediately.	1 per definitive result
get_job_status	Progress counters, optionally per-number results.	Free
list_jobs	Recent bulk jobs on the account.	Free
get_balance	Credits remaining.	Free

Prompts

Clients that support MCP prompts surface these as slash commands.

Prompt	Arguments	What it does
/check_numbers	numbers	Validate a list and summarise which are reachable on WhatsApp.
/clean_contact_list	numbers, purpose	Audit a list before a campaign, and report what to fix.
/check_before_spending	count	Estimate the cost of a run and check the balance covers it.

Billing, and why it should change how an agent uses this

One credit per definitive answer — registered or not registered. Beyond that:

• Invalid and unparseable numbers cost nothing. Send them. An agent that pre-filters numbers it is unsure about drops real contacts to save credits it was never going to spend.
• An inconclusive upstream result costs nothing.
• Credits never expire.

Numbers should be E.164 (+14155550100). Past a handful, prefer bulk_validate over a loop of validate_number: it is one job to poll rather than N round trips.

Options

--token <key>	Your API key. Also read from NUMRADAR_API_KEY; the flag wins if both are set.
--base <url>	API origin. Defaults to https://numradar.app.
--version	Print the version and exit.
--help	Print usage and exit.

Security

The API key is a bearer credential for your account. --token puts it in your shell history and in whatever config file spawns the process — prefer NUMRADAR_API_KEY from a secret store where your client supports it. Keys are revocable from the dashboard; revoke immediately if one is exposed.

Every tool call is authenticated, rate-limited and billed through numradar's ordinary public REST API. The MCP server does not embed the checker and has no separate billing path, so an agent calling a tool is treated exactly like a backend calling curl.

About this repository

This is the home of the npm package —

... View full README on GitHub