# @bubblyphone/mcp-server

MCP server for [BubblyPhone](https://agents.bubblyphone.com) — make AI phone calls, manage voice agents, and track billing from any AI assistant.

[![npm version](https://img.shields.io/npm/v/@bubblyphone/mcp-server.svg)](https://www.npmjs.com/package/@bubblyphone/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What is BubblyPhone?

BubblyPhone is a telephony platform for AI voice agents. You get a real phone number, connect an AI model (Gemini, GPT), give it a system prompt, and it handles phone calls autonomously — booking reservations, answering support questions, qualifying leads, or anything you can describe in plain English.

This MCP server lets you control all of that from any AI assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io).

## Quick Start

### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bubblyphone": {
      "command": "npx",
      "args": ["@bubblyphone/mcp-server"],
      "env": {
        "BUBBLYPHONE_API_KEY": "bp_live_sk_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "bubblyphone": {
      "command": "npx",
      "args": ["@bubblyphone/mcp-server"],
      "env": {
        "BUBBLYPHONE_API_KEY": "bp_live_sk_your_key_here"
      }
    }
  }
}
```

### ChatGPT

Connect to the remote MCP server at `https://agents.bubblyphone.com/mcp` — authentication is handled via OAuth.

### Remote (Streamable HTTP)

Connect any MCP client to `https://agents.bubblyphone.com/mcp` with your API key as a Bearer token.

## Available Tools

### Calls
| Tool | Description |
|------|-------------|
| `make_call` | Initiate an outbound AI phone call |
| `list_calls` | List calls with filtering |
| `get_call` | Get call details |
| `hangup_call` | Terminate an active call |
| `transfer_call` | Transfer a call to another number |
| `inject_context` | Send context to an AI agent mid-call |
| `get_call_transcript` | Get call transcript |
| `get_call_events` | Get call event log |

### Phone Numbers
| Tool | Description |
|------|-------------|
| `search_phone_numbers` | Search available numbers in 30+ countries |
| `list_phone_numbers` | List your numbers |
| `buy_phone_number` | Purchase a number |
| `get_phone_number` | Get number details and AI config |
| `update_phone_number` | Configure AI agent settings |

### Billing
| Tool | Description |
|------|-------------|
| `get_balance` | Check credit balance |
| `get_usage` | Usage statistics |
| `list_transactions` | Transaction history |

### Models & Rates
| Tool | Description |
|------|-------------|
| `list_models` | Available AI models and pricing |
| `lookup_rate` | Rate for a phone number |
| `get_country_rates` | Rates by country |

### Account
| Tool | Description |
|------|-------------|
| `get_account` | Account information |

## Use Cases

- **"Call this restaurant and make a reservation for Friday at 7pm"**
- **"Set up a 24/7 customer support line for my business"**
- **"Call my doctor's office and reschedule my appointment"**
- **"Create a phone agent that qualifies sales leads"**

## Get Your API Key

1. Sign up at [agents.bubblyphone.com](https://agents.bubblyphone.com)
2. Go to Dashboard > API Keys
3. Create a new API key

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio)
BUBBLYPHONE_API_KEY=your_key node dist/bin/cli.js

# Run locally (HTTP)
node dist/index.js --http --port 3100
```

## License

MIT