NumRadar MCP server
✓ VerifiedVerifies whether phone numbers are registered on WhatsApp through single or bulk validation tools.
Also known as numradar/mcp, mcp, @numradar/mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.2.2
- Last commit
- Aug 12, 2026
- License
- MIT
What is NumRadar MCP?
NumRadar verifies whether phone numbers are registered on WhatsApp through single or bulk validation tools. It exposes 5 tools, such as validate_number, bulk_validate, get_job_status.
Summary generated from the project's README
About NumRadar MCP server
NumRadar provides a way for AI agents to verify if phone numbers are registered on WhatsApp. It functions as a hosted MCP server that connects via a URL and an authorization header, though an npm package is available for clients that require a command to spawn a local process. Users must provide an API key to authenticate their requests and manage credits.
The server includes specific tools for different scales of work. The validate_number tool checks a single number for registration status, line type, and country, while the bulk_validate tool handles up to 10,000 numbers at once by returning a job id. Users can monitor these large tasks using get_job_status and list_jobs, or check their remaining credits with get_balance.
This setup is designed for developers using clients like Claude Code, Cursor, or Windsurf. It offers a cost-effective model where invalid or unparseable numbers do not consume credits, allowing agents to filter data without wasting resources. All tool calls are authenticated and rate-limited through the standard NumRadar REST API.
What you can do with it
- 1Verify single phone numbersAn agent can check if a specific number is a business account or a standard line on WhatsApp.
- 2Audit large contact listsA developer can instruct an AI to validate a massive list of numbers before starting a marketing campaign.
- 3Manage operational costsAn AI can estimate the total cost of a validation task and ensure the account has enough credits first.
- 4Process bulk validation jobsUsers can submit up to 10,000 numbers at once to receive a job identifier for tracking.
Written from the project's README. Every use case is checked against a quote from it.
How to install NumRadar MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall NumRadar MCP in Claude Code
$ claude mcp add --env 'NUMRADAR_KEY=<YOUR_NUMRADAR_KEY>' mcp -- npx -y @numradar/mcpInstall NumRadar MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numradar/mcp"
],
"env": {
"NUMRADAR_KEY": "<YOUR_NUMRADAR_KEY>"
}
}
}
}Install NumRadar MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@numradar/mcp"
],
"env": {
"NUMRADAR_KEY": "<YOUR_NUMRADAR_KEY>"
}
}
}
}Install NumRadar MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@numradar/mcp"],"env":{"NUMRADAR_KEY":"<YOUR_NUMRADAR_KEY>"}}'Install NumRadar MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numradar/mcp"
],
"env": {
"NUMRADAR_KEY": "<YOUR_NUMRADAR_KEY>"
}
}
}
}Install NumRadar MCP in Codex
$ codex mcp add mcp --env 'NUMRADAR_KEY=<YOUR_NUMRADAR_KEY>' -- npx -y @numradar/mcpInstall NumRadar MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@numradar/mcp"] [mcp_servers.mcp.env] NUMRADAR_KEY = "<YOUR_NUMRADAR_KEY>"
Install NumRadar MCP in Gemini CLI
$ gemini mcp add -s user -e 'NUMRADAR_KEY=<YOUR_NUMRADAR_KEY>' mcp npx -- -y @numradar/mcpInstall NumRadar MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numradar/mcp"
],
"env": {
"NUMRADAR_KEY": "<YOUR_NUMRADAR_KEY>"
}
}
}
}NumRadar MCP tools 5
Detected from the READMEvalidate_numberbulk_validateget_job_statuslist_jobsget_balance
Configuration
NUMRADAR_KEYRequiredSecretnumradar API key (nr_live_...). Create one at https://numradar.app/app/keys
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenumradar/mcp is public and reachablegithub.com/numradar/mcp ↗Pass
- Package names this repository as its source@numradar/mcp names numradar/mcp as sourcenpmjs.com/package/@numradar/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/numradar/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @numradar/mcpPass
- No critical advisory in the package or its dependencies59 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHub@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 — its issue tracker and documentation. The server's source lives in a private monorepo and is not published here.
Found a bug, or a client whose configuration does not work? Open an issue.
- API documentation
- MCP reference and per-client configuration
- Agent skills and the Claude Code plugin
Licence
MIT
NumRadar MCP questions
How do I add NumRadar MCP to Claude Code?
Run claude mcp add --env 'NUMRADAR_KEY=<YOUR_NUMRADAR_KEY>' mcp -- npx -y @numradar/mcp in your terminal. Add --scope user to make it available in every project.
How do I add NumRadar MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does NumRadar MCP provide?
It exposes 5 tools, including validate_number, bulk_validate, get_job_status, list_jobs, get_balance.
How much does it cost to validate a number?
One credit is charged per definitive answer, whether the number is registered or not. Invalid or unparseable numbers cost nothing.
Can I validate multiple numbers at once?
Yes, you can use the bulk_validate tool to check up to 10,000 numbers at a time.
Do I need to install anything to use NumRadar?
No, it runs as a hosted MCP server that you can point your client to via a URL.