Getting Started

This guide provides an overview of the requirements and environment configurations for the Bandwidth MCP Server Package. A more detailed description, including set-up instructions, agent configurations, and code snippets, can be found in the Github repository. Most of our guidance is replicated here for your convenience, but we recommend following the README in full before using the package.

Prerequisites

... for all use cases:

• Valid Bandwidth API Credentials
  • This will be the username and password of your Bandwidth API user
  • For more info on creating API credentials, see our Credentials page
• Bandwidth Account ID
  • The ID of the account you'd like to make API calls on behalf of

info

Users will only be able to use tools for features that are already authorized by their API credentials and provisioned on their account.

... for some use cases:

• BW_NUMBER: A valid phone number on your account. Must be in E.164 format.
• BW_MESSAGING_APPLICATION_ID: A Bandwidth messaging Application ID.
• BW_VOICE_APPLICATION_ID: A Bandwidth voice Application ID.

Installation

You can find the MCP server source code here. Follow the instructions in the README to install the package, configure environment variables, and run the server standalone or alongside your agent of choice.

Connecting to your Agent

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

1. 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.
2. Configure your Goose provider following the Goose CLI set-up instructions
3. Add the Bandwidth MCP Server as a Command-line Extension

┌   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

Cursor

1. Install Cursor
2. 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_USERNAME": "<insert-bw-username>",
                "BW_PASSWORD": "<insert-bw-password>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude",
            }
        }
    }
}

VSCode (Copilot)

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

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

3. 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.
4. 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_USERNAME": "<insert-bw-username>",
                "BW_PASSWORD": "<insert-bw-password>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude",
            }
        }
    },
    "inputs": []
}

Claude Desktop

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

{
    "mcpServers": {
        "Bandwidth": {
            "command": "uvx",
            "args": ["--from", "/path/to/mcp-server", "start"],
            "env": {
                "BW_USERNAME": "<insert-bw-username>",
                "BW_PASSWORD": "<insert-bw-password>",
                "BW_MCP_TOOLS": "tools,to,enable",
                "BW_MCP_EXCLUDE_TOOLS": "tools,to,exclude"
            }
        }
    }
}

Tools

Enabling Tools

By default, the server provides and enables all tools listed in the Available Tools. 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 Available Tools. The BW_MCP_TOOLS and BW_MCP_EXCLUDE_TOOLS environment variables 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. All available tools are listed below, or try asking your agent, "What tools are available for the Bandwidth MCP server?". See our Example Use Cases for a few sample scenarios and tools to enable for a given action.

Available Tools

Multi-Factor Authentication (MFA)

• generateMessagingCode - Send MFA code via SMS
• generateVoiceCode - Send MFA code via voice call
• verifyCode - Verify a previously sent MFA code

Phone Number Lookup

• createLookup - Create a phone number lookup request
• getLookupStatus - Get status of an existing lookup request

Voice & Call Management

• listCalls - Returns a list of call events with filtering options
• listCall - Returns details for a single call event

Reporting & Analytics

• getReports - Get history of created reports
• createReport - Create a new report instance
• getReportStatus - Get status of a report
• getReportFile - Download report file
• getReportDefinitions - Get available report definitions

Media Management

• listMedia - List your media files
• getMedia - Download a specific media file
• uploadMedia - Upload a media file
• deleteMedia - Delete a media file

Messaging

• listMessages - List messages with filtering options
• createMessage - Send SMS/MMS messages
• createMultiChannelMessage - Send multi-channel messages (RBM, SMS, MMS)

Address Management

• getAddressFields - Get supported address fields by country
• validateAddress - Validate an address and get excluded features
• listAddresses - List all addresses
• createAddress - Create an address
• getAddress - Get an address by ID
• updateAddress - Update an address
• listCityInfo - List city info search results

Compliance

• listDocumentTypes - List all accepted document types and metadata requirements
• listEndUserTypes - List all End user types and accepted metadata
• listEndUserActivationRequirements - List requirements for End user activation
• getComplianceDocumentMetadata - Get metadata of uploaded documents
• updateComplianceDocument - Modify document data and file
• downloadComplianceDocuments - Download document using document ID
• createComplianceDocument - Upload a document with metadata
• listComplianceEndUsers - List all End users of an account
• createComplianceEndUser - Create an End user
• getComplianceEndUser - Retrieve an End User by ID
• updateComplianceEndUser - Update End user details

Requirements Packages

• listRequirementsPackages - List all requirements packages
• createRequirementsPackage - Create a requirements package
• getRequirementsPackage - Retrieve a requirements package
• patchRequirementsPackage - Update Requirements package
• getRequirementsPackageAssets - Get assets attached to requirements package
• attachRequirementsPackageAsset - Attach an asset to requirements package
• detachRequirementsPackageAsset - Detach an asset from requirements package
• validateNumberActivation - Validate number activation requirements
• getRequirementsPackageHistory - Get history of a requirements package