VoIPbin MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with the VoIPbin CPaaS platform. It exposes VoIPbin's communication APIs -- calls, flows, messaging, conferencing, AI, and more -- as tools that any MCP-compatible client can use to manage and automate cloud communications.

Installation

The client configurations below all launch the server with uvx, which fetches and runs it without a manual install:

uvx voipbin-mcp

To install it into an environment instead:

pip install voipbin-mcp

Requires Python 3.10 or newer.

Configuration

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "voipbin": {
      "command": "uvx",
      "args": ["voipbin-mcp"],
      "env": {
        "VOIPBIN_API_KEY": "your-access-key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "voipbin": {
      "command": "uvx",
      "args": ["voipbin-mcp"],
      "env": {
        "VOIPBIN_API_KEY": "your-access-key"
      }
    }
  }
}

Generic MCP Client

Any MCP-compatible client can connect by running the voipbin-mcp command with the VOIPBIN_API_KEY environment variable set:

VOIPBIN_API_KEY=your-access-key voipbin-mcp

Available Tools

Example Usage

Once configured, you can ask your AI assistant to interact with VoIPbin directly:

List active calls:

"Show me all my active calls"

The AI uses list_calls to fetch and display your current calls.

Create a flow:

"Create a flow that answers and plays a greeting"

The AI uses create_flow to build a call flow with answer and play actions.

Check billing:

"What are my recent billing charges?"

The AI uses list_billings to retrieve your billing history.

Manage contacts:

"Add a new contact named John with phone number +1234567890"

The AI uses create_contact, passing the number as an address of type tel.

Configuration reference

Security Note

Your VoIPbin API key is sent in a Cookie header on every request, over HTTPS. Earlier releases sent it as a URL query parameter (accesskey=), which leaves the key in server access logs and proxy logs.

If a proxy or ingress in front of your deployment strips or rewrites cookies, set VOIPBIN_AUTH_TRANSPORT=query to fall back to the query parameter. Prefer fixing the proxy: the query form has the logging exposure described above.

Avoid sharing unredacted debug output, and rotate your key if you suspect it has been exposed. When configuring an AI agent with create_ai, pass an environment variable reference for engine_key rather than a literal provider key; that value is stored by the API and can appear in responses.

Known limitations

• Around 12% of the VoIPbin REST API is exposed as tools. Coverage expands in later releases.
• list_routes and get_route are platform-level and answer 403 for a normal customer access key.
• create_conference does not expose the data field; it always sends an empty object.
• Attachments on send_email reference existing VoIPbin objects (such as a recording) rather than uploading file contents.

Getting an API Key

Sign up at voipbin.net and create an access key through the API or the admin console at admin.voipbin.net.

Development

git clone https://github.com/voipbin/mcp.git
cd mcp
uv venv
uv pip install -e ".[dev]"
uv run pytest tests/ -v

The release gate builds the distribution and installs it at both ends of the declared mcp range, because a package can pass in the lock environment and still be broken for everyone installing from PyPI. To reproduce that locally:

uv build
uv run python scripts/stdio_smoke.py

Tool descriptions are pinned by exact text in tests/golden_docstrings.json, so any docstring edit fails the suite until the golden file is regenerated. That is intentional: ten documented behaviours in this package turned out to contradict the backend, so an edit is the moment to re-read the Go source named beside the claim in PINNED_CLAIMS and confirm it still holds. Once verified:

# optional but recommended: check every pinned Go reference still resolves
VOIPBIN_MONOREPO=/path/to/monorepo uv run pytest tests/ -k resolve
uv run python scripts/update_golden_docstrings.py

License

MIT