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, Claude Code, and any MCP-compatible client.

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "botcall": {
      "command": "npx",
      "args": ["-y", "botcall-mcp"],
      "env": {
        "BOTCALL_API_KEY": "bs_live_..."
      }
    }
  }
}

Claude Code

claude mcp add botcall -- npx -y botcall-mcp

Then set your API key in the environment:

export BOTCALL_API_KEY="bs_live_..."

Other MCP clients

Any client that supports the MCP stdio transport works. Run npx botcall-mcp with BOTCALL_API_KEY set.

Get an API key

Sign up at 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