Bandwidth Official MCP Server

Source code for the official Bandwidth Model Context Protocol (MCP) Server. This server can be used to interact with different Bandwidth APIs via an AI agent. The server is provided as a python package and may be cloned directly from this repo.

Installation

Clone directly from this git repository using:

git clone https://github.com/Bandwidth/mcp-server.git
cd mcp-server

Getting Started

Prerequisites

In order to use the Bandwidth MCP Server, you'll need the following things, set as environment variables.

Valid Bandwidth OAuth2 Client Credentials
- You will need a client ID and client secret for your Bandwidth API application
- For more info on creating API credentials, see our Credentials page
Your account ID is auto-discovered from JWT claims after authentication — you do not need to provide it

Configuration

Environment Variables

Environment variables are used to configure the Bandwidth MCP Server. The server will respect both system environment variables and those configured via your AI agent.

The following variables will be required to use the server:

BW_CLIENT_ID     # Your Bandwidth OAuth2 client ID
BW_CLIENT_SECRET # Your Bandwidth OAuth2 client secret

The following variables are optional or conditionally required:

BW_ACCOUNT_ID               # Your Bandwidth Account ID. Optional — auto-discovered from JWT claims after authentication.
BW_NUMBER                   # A valid phone number on your Bandwidth account. Used with our Messaging API. Must be in E164 format.
BW_MESSAGING_APPLICATION_ID # A Bandwidth Messaging Application ID. Used with our Messaging API.
BW_VOICE_APPLICATION_ID     # A Bandwidth Voice Application ID. Used to auto-configure voice callbacks in hosted mode.
BW_MCP_PROFILE              # Named tool preset (voice, messaging, lookup, onboarding, recordings, full). Comma-separated to combine.
BW_MCP_TOOLS                # Explicit tool allowlist (comma-separated operationIds). Overrides BW_MCP_PROFILE.
BW_MCP_EXCLUDE_TOOLS        # Explicit tool denylist (comma-separated). Takes priority over BW_MCP_TOOLS and profiles.
BW_ENVIRONMENT              # `test` or `uat` to target Bandwidth's test environment. Defaults to prod.
BW_API_URL                  # API gateway override. Also serves the Dashboard XML API under /api/v2.
BW_VOICE_URL                # Voice API base override.
BW_MESSAGING_URL            # Messaging API base override.

Including or Excluding Tools

By default, the server provides and enables all tools listed in the Tools List. Enabling all of these tools may cause context window size issues for certain AI agents or lead to slower agent response times. To work around this and for a better experience, we recommend enabling only the certain subset of tools you plan on using.

This can be accomplished by supplying a list of tool names to specifically enable or exclude to the server. This list must be comma separated, with the tool names matching their names in the Tools List. The BW_MCP_TOOLS and BW_MCP_EXCLUDE_TOOLS mentioned in the Environment Variables section allow for enabling and excluding tools by name. You can also use the CLI flags --tools and --exclude-tools. Using the CLI flags will take priority over the environment variables, and providing tools to exclude will take priority over the list of enabled tools.

For a more comprehensive list of common use cases when which tools are required for each, check out our Common Use Cases Guide.

Tool Filtering Examples

Including only our Messaging tools

# Environment Variable
BW_MCP_TOOLS=listMessages,createMessage,createMultiChannelMessage

# CLI Flag
--tools listMessages,createMessage,createMultiChannelMessage

Excluding our Phone Number Lookup Tools

# Environment Variable
BW_MCP_EXCLUDE_TOOLS=createLookup,getLookupStatus

# CLI Flag
--exclude-tools createLookup,getLookupStatus

Account Creation Flow (Build Registration)

Bandwidth Build is the free voice-first trial. Use this profile when the user has no credentials yet. The MCP only exposes createRegistration to kick things off — SMS verification, password set, and API credential generation all happen in pages Bandwidth links the user to. The agent shouldn't try to consume the SMS code over the API; it belongs to the user's browser flow.

BW_MCP_TOOLS=createRegistration

Using the Server

Below you'll find instructions for using our MCP server with different common AI agents, as well as instructions for running the server locally. For usage with AI agents, it is recommended to use a combination of uv and environment variables to start and configure the server respectively.

Goose CLI

Install Goose CLI
- We recommend configuring Goose to use Allow Mode. This will require user approval before Goose calls tools, which could prevent Goose from accidentally taking unwanted actions.
Add the Bandwidth MCP Server as a Command-line Extension

goose configure

Then follow the prompts like the example below.

┌   goose-configure
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◇  What would you like to call this extension?
│  bw-mcp-server
│
◇  What command should be run?
│  uvx --from /path/to/mcp-server start

NOTE: If you configure environment variables with Goose, it will prioritize those over your system environment variables.

Cursor

Install Cursor
Update your .cursor/mcp.json file to include the following object

{
    "mcpServers": {
        "bw-mcp-server": {
            "command":"uvx",
            "args": ["--from", "/path/to/mcp-server", "start"],
            "env": {
                "BW_CLIENT_ID": "<insert-bw-client-id>",
                "BW_CLIENT_SECRET": "<insert-bw-client-secret>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude",
            }
        }
    }
}

VSCode (Copilot)

Within VSCode, open the Command Palette and search for MCP: Add Server.
Choose Command (stdio), then enter the full command to start the server. (Example Below)

uvx --from /path/to/mcp-server start

Choose a name for the server (ie. bw-mcp-server) and select if you'd like it to be enabled Globally or only in the current workspace.
You can configure environment variables by opening the mcp.json file VSCode provides like the example below.

{
    "servers": {
        "bw-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": ["--from", "/path/to/mcp-server", "start"],
            "env": {
                "BW_CLIENT_ID": "<insert-bw-client-id>",
                "BW_CLIENT_SECRET": "<insert-bw-client-secret>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude",
            }
        }
    },
    "inputs": []
}

NOTE: You may need to make sure MCP servers are enabled in VSCode to begin using the server. See the official guide for more info.

Claude Desktop

Install Claude Desktop
Edit your claude_desktop_config.json to include the following object

{
    "mcpServers": {
        "Bandwidth": {
            "command": "uvx",
            "args": ["--from", "/path/to/mcp-server", "start"],
            "env": {
                "BW_CLIENT_ID": "<insert-bw-client-id>",
                "BW_CLIENT_SECRET": "<insert-bw-client-secret>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude",
            }
        }
    }
}

NOTE: We've noticed some issues with Claude not being able to see MCP resources. This could require you to manually enter some tool parameters normally included in our config resource.

Running the Server Standalone

The MCP server can be run locally using either native python or uv. When running this way, all environment variables MUST be set in your system environment.

Run Using Native Python

Running the server locally with a python virtual environment requires both python and pip. Once these are installed, create a virtual environment using:

python -m venv .venv

Then activate and install the project with its dependencies.

source .venv/bin/activate
pip install .

After all packages are installed in the virtual environment, you can run the server locally using:

python src/app.py

Run Using uv

Make sure you have uv installed, then you can start the server by running the following command from the root directory of this repository.

uvx --from ./ start

Hosted Mode

Run the server over HTTP to enable remote access and webhook callbacks:

BW_MCP_TRANSPORT=streamable-http \
BW_MCP_PORT=8080 \
BW_MCP_BASE_URL=https://your-server.example.com \
BW_CLIENT_ID=your_client_id \
BW_CLIENT_SECRET=your_client_secret \
python src/app.py

Local Callback Tunnel (dev only)

Voice and messaging callbacks need Bandwidth to reach your server over a public URL. In production you set BW_MCP_BASE_URL. For local development, set BW_MCP_DEV_TUNNEL=1 and the server will open an ephemeral cloudflared tunnel, use the resulting *.trycloudflare.com URL as BW_MCP_BASE_URL, and auto-wire your voice app's callbacks to it — no ngrok needed.

BW_MCP_TRANSPORT=streamable-http \
BW_MCP_DEV_TUNNEL=1 \
BW_CLIENT_ID=your_client_id \
BW_CLIENT_SECRET=your_client_secret \
python src/app.py

Requires cloudflared on your PATH (brew install cloudflared on macOS). If it's missing, the server logs a warning and starts without a tunnel. This is for development and testing only — production deployments should use a real host via BW_MCP_BASE_URL. The tunnel never starts unless BW_MCP_DEV_TUNNEL is set.

Tool Profiles

Reduce context window pressure with named presets:

BW_MCP_PROFILE=messaging    # SMS/MMS tools only
BW_MCP_PROFILE=voice        # Voice + BXML tools
BW_MCP_PROFILE=onboarding   # Account creation
BW_MCP_PROFILE=lookup       # Number intelligence
BW_MCP_PROFILE=messaging,voice  # Combine profiles

Profiles set via BW_MCP_PROFILE env var or --profile CLI flag. Use BW_MCP_TOOLS to override with specific tool names.

Tools List

Tools are grouped into profiles that mirror the workflows you'd use the server for. Loading a single profile keeps your agent's context small. The full agent reference — including auth model, error codes, and the "trust nothing" guidance for async calls — lives in src/specs/AGENTS.md.

The default tool set is voice + messaging + lookup (plus setCredentials / clearCredentials, always loaded). Override with BW_MCP_PROFILE, BW_MCP_TOOLS, or BW_MCP_EXCLUDE_TOOLS.

Session management (always loaded)

setCredentials — authenticate the session (stdio transport only)
clearCredentials — log out of the session

Profile: `onboarding` (no auth required)

Kicks off a new Bandwidth Build account. Only one tool is exposed — SMS verification, password set, and API credential generation all happen in the user's browser. The agent hands off after the kickoff.

createRegistration — submit contact details; Bandwidth then SMSes an OTP and emails a password-set link

Profile: `voice`

listApplications / createApplication — find or create a voice app
listPhoneNumbers — find numbers on the account
createCall — place an outbound call
getCallState — read current call state (always poll after createCall)
listCalls — list call events with filtering
updateCall / updateCallBxml — redirect, hang up, or replace BXML
generateBXML — build valid BXML from a verb list
respondToCallback — queue a BXML response for an active callback (first-write-wins)
getCallbackEvents — read recent voice / messaging callback events
configureCallbacks — point an application's webhook URLs at this server

Profile: `messaging`

createMessage — send SMS / MMS
listMessages — query message history
getInboundMessages — read inbound messages captured by this server
listMedia / getMedia / uploadMedia / deleteMedia — manage MMS media
configureCallbacks — point an application's callbacks at this server

Profile: `lookup`

createSyncLookup — one-shot lookup for a small input set
createAsyncBulkLookup — kick off a bulk lookup
getAsyncBulkLookup — poll a bulk lookup

Profile: `recordings`

listCallRecordings / getCallRecording — list / inspect recordings
downloadCallRecording — download the media
deleteRecording — remove a recording
transcribeCallRecording / getRecordingTranscription — request and read transcription

See src/specs/AGENTS.md for argument-level guidance, polling patterns, and the structured error shape the server returns on failure.

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.bandwidth		.bandwidth
.github		.github
src		src
test		test
.gitignore		.gitignore
README.md		README.md
common_use_cases.md		common_use_cases.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Bandwidth Official MCP Server

Installation

Getting Started

Prerequisites

Configuration

Environment Variables

Including or Excluding Tools

Tool Filtering Examples

Using the Server

Goose CLI

Cursor

VSCode (Copilot)

Claude Desktop

Running the Server Standalone

Run Using Native Python

Run Using uv

Hosted Mode

Local Callback Tunnel (dev only)

Tool Profiles

Tools List

Session management (always loaded)

Profile: `onboarding` (no auth required)

Profile: `voice`

Profile: `messaging`

Profile: `lookup`

Profile: `recordings`

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Bandwidth Official MCP Server

Installation

Getting Started

Prerequisites

Configuration

Environment Variables

Including or Excluding Tools

Tool Filtering Examples

Using the Server

Goose CLI

Cursor

VSCode (Copilot)

Claude Desktop

Running the Server Standalone

Run Using Native Python

Run Using uv

Hosted Mode

Local Callback Tunnel (dev only)

Tool Profiles

Tools List

Session management (always loaded)

Profile: onboarding (no auth required)

Profile: voice

Profile: messaging

Profile: lookup

Profile: recordings

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Profile: `onboarding` (no auth required)

Profile: `voice`

Profile: `messaging`

Profile: `lookup`

Profile: `recordings`

Packages