# 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