MCP server for AI agents

Let an AI agent get a real phone number and read the SMS code. numberotp-mcp runs on your machine with Node 20+ and talks to your account through an API key.

1Create a key for the agent

Open Dashboard → Developer and create a key with the read and buy scopes, or use the CLI: notp keys create agent --scope read,buy.

A read,buy key can buy and read numbers but can never manage keys, webhooks or your account. Add the topup scope only if you want the agent to create payment links for you.

2Add the server to your client

claude mcp add numberotp --env NOTP_API_KEY=notp_… --env NOTP_MAX_SPEND=5 -- npx -y numberotp-mcp

Restart the client, then ask something like: “Get me a UK number for WhatsApp and tell me the code.”

3Settings

Variable	Default	What it does
`NOTP_API_KEY`	required	The key from step 1
`NOTP_MAX_SPEND`	5	Most one session may spend on numbers, in USD
`NOTP_BASE_URL`	`https://api.numberotp.com/v1`	Only change this for a reseller white-label domain

4Tools the agent gets

Tool	What it does
`search_services`	Name, code or website → service code
`get_prices`	Price, stock and success rate by country
`buy_number`	Buy a number, within the budget and an optional max price
`wait_for_code`	Wait for the code (up to 120 s per call; the agent calls again if needed)
`get_number` / `list_numbers`	Status, code and every SMS
`request_another_sms`	A second code on the same number
`cancel_number` / `finish_number`	Refund when nothing arrived / close when done
`rent_number` / `get_rental`	Longer-term numbers
`get_balance`	Balance, money on hold and budget left
`create_topup_link`	A payment link for you — the agent never pays

5Troubleshooting

The server doesn't start: check node --version is 20 or newer, and that NOTP_API_KEY is set in the client's config (not just your shell).
“The account balance is too low”: top up in the dashboard, or let the agent create a link with a key that has the topup scope.
“…this session's budget has $0.40 left”: the spending cap was reached. Raise NOTP_MAX_SPEND and restart the client.
See what the agent did: every number is in your dashboard, and notp events tail shows events live.

Package: numberotp-mcp on npm. Prefer writing the integration yourself? See the SDK guide.