botcall-mcp
by danecodes
README.md
# botcall-mcp
An MCP server that gives AI agents real phone numbers. Provision a number, receive SMS, and extract verification codes — all through tool calls.
Built for [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and any MCP-compatible client.
## Setup
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"botcall": {
"command": "npx",
"args": ["-y", "botcall-mcp"],
"env": {
"BOTCALL_API_KEY": "bs_live_..."
}
}
}
}
```
### Claude Code
```bash
claude mcp add botcall -- npx -y botcall-mcp
```
Then set your API key in the environment:
```bash
export BOTCALL_API_KEY="bs_live_..."
```
### Other MCP clients
Any client that supports the [MCP stdio transport](https://modelcontextprotocol.io) works. Run `npx botcall-mcp` with `BOTCALL_API_KEY` set.
## Get an API key
Sign up at [botcall.io](https://botcall.io), pick a plan, and grab your key from Dashboard → API Keys.
## Tools
### `provision_number`
Provision a new phone number for receiving SMS.
| Parameter | Type | Description |
|-----------|------|-------------|
| `areaCode` | string | Preferred area code, e.g. `"206"` (optional) |
| `country` | string | ISO country code (default: `"US"`) |
### `get_code`
Wait for an incoming SMS and extract the verification code. Long-polls until a message arrives or the timeout expires.
| Parameter | Type | Description |
|-----------|------|-------------|
| `timeout` | number | Seconds to wait (default: 30, max: 30) |
| `numberId` | string | Filter to a specific number (optional) |
### `get_inbox`
Get recent SMS messages received on your numbers.
| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Max messages to return (default: 10) |
| `numberId` | string | Filter to a specific number (optional) |
### `list_numbers`
List all your provisioned phone numbers. No parameters.
### `release_number`
Release a phone number you no longer need.
| Parameter | Type | Description |
|-----------|------|-------------|
| `numberId` | string | **Required.** The number ID to release |
### `get_usage`
Get your current plan, limits, and usage stats. No parameters.
## Example
```
You: Sign up for ExampleService using a phone number
Agent: I'll provision a number and handle the verification.
→ provision_number({ areaCode: "415" })
{ number: "+14155550123", id: "pn_abc123" }
→ [agent enters the number on ExampleService's signup page]
→ get_code({ numberId: "pn_abc123" })
Verification code: 847291
→ [agent enters 847291 to complete verification]
```
## Environment variables
| Variable | Description |
|----------|-------------|
| `BOTCALL_API_KEY` | **Required.** Your API key from botcall.io |
| `BOTCALL_API_URL` | API base URL (default: `https://api.botcall.io`) |
## License
MIT
TDQS
A4/5.0
Scored across 6 tools
Disambiguation5/5
Each tool has a clear, distinct purpose: waiting for a code, viewing inbox, usage stats, listing numbers, provisioning, and releasing numbers. No overlap in functionality.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case, using verbs like get, list, provision, release. No mixing of conventions.
Tool Count5/5
With 6 tools, the set is well-scoped for an SMS verification and number management server. Each tool serves a necessary role without excess or deficiency.
Completeness5/5
The tool surface covers the full lifecycle of number management (list, provision, release) and SMS retrieval (inbox, code waiting) along with usage tracking. No obvious gaps for the stated purpose.