内容
# 官方Bandwidth MCP服务器
Bandwidth官方模型上下文协议（MCP）服务器的源代码。此服务器可用于通过AI代理与不同的Bandwidth API交互。服务器作为Python包提供，可以直接从此仓库克隆。
## 安装
使用以下命令直接从git仓库克隆：
```shell
git clone https://github.com/Bandwidth/mcp-server.git
cd mcp-server
```
## 入门指南
### 先决条件
要使用Bandwidth MCP服务器，您需要以下内容，并将其设置为环境变量。
- 有效的Bandwidth OAuth2客户端凭证
- 您需要您的Bandwidth API应用程序的客户端ID和客户端密钥
- 有关创建API凭证的更多信息，请参见我们的[凭证](https://dev.bandwidth.com/docs/credentials)页面
- 您的账户ID在身份验证后从JWT声明中自动发现 - 您无需提供它
### 配置
#### 环境变量
环境变量用于配置Bandwidth MCP服务器。服务器将尊重系统环境变量和通过AI代理配置的变量。
使用服务器需要以下变量：
```sh
BW_CLIENT_ID # 您的Bandwidth OAuth2客户端ID
BW_CLIENT_SECRET # 您的Bandwidth OAuth2客户端密钥
```
以下变量是可选或有条件的必需：
```sh
BW_ACCOUNT_ID # 您的Bandwidth账户ID。可选 - 在身份验证后从JWT声明中自动发现。
BW_NUMBER # 您的Bandwidth账户上的有效电话号码。用于我们的消息API。必须为E164格式。
BW_MESSAGING_APPLICATION_ID # Bandwidth消息应用程序ID。用于我们的消息API。
BW_VOICE_APPLICATION_ID # Bandwidth语音应用程序ID。用于在托管模式下自动配置语音回调。
BW_MCP_PROFILE # 命名工具预设（voice，messaging，lookup，onboarding，recordings，full）。用逗号分隔以组合。
BW_MCP_TOOLS # 显式工具允许列表（逗号分隔的操作ID）。覆盖BW_MCP_PROFILE。
BW_MCP_EXCLUDE_TOOLS # 显式工具拒绝列表（逗号分隔）。优先级高于BW_MCP_TOOLS和配置文件。
BW_ENVIRONMENT # `test`或`uat`以定位Bandwidth的测试环境。默认为prod。
BW_API_URL # API网关覆盖。也为/api/v2提供Dashboard XML API。
BW_VOICE_URL # 语音API基本覆盖。
BW_MESSAGING_URL # 消息API基本覆盖。
```
#### 包含或排除工具
默认情况下，服务器提供并启用[工具列表](#工具列表)中列出的所有工具。
启用所有这些工具可能会导致某些AI代理的上下文窗口大小问题或导致代理响应时间变慢。
为了避免这种情况并获得更好的体验，我们建议仅启用您计划使用的某些工具的子集。
可以通过向服务器提供要启用或排除的工具列表来实现这一点。
此列表必须用逗号分隔，工具名称与[工具列表](#工具列表)中的名称匹配。
`BW_MCP_TOOLS`和`BW_MCP_EXCLUDE_TOOLS`在[环境变量](#环境变量)部分中提到，允许按名称启用和排除工具。您还可以使用CLI标志`--tools`和`--exclude-tools`。
使用CLI标志将优先于环境变量，而提供要排除的工具将优先于启用的工具列表。
有关每个工具所需的常见用例的综合列表，请查看我们的[常见用例指南](common_use_cases.md)。
##### 工具过滤示例
**仅包含我们的消息工具**
```sh
# 环境变量
BW_MCP_TOOLS=listMessages,createMessage,createMultiChannelMessage
# CLI标志
--tools listMessages,createMessage,createMultiChannelMessage
```
**排除我们的电话号码查找工具**
```sh
# 环境变量
BW_MCP_EXCLUDE_TOOLS=createLookup,getLookupStatus
# CLI标志
--exclude-tools createLookup,getLookupStatus
```
**帐户创建流程（构建注册）**
Bandwidth Build是免费的语音优先试用。 在用户没有凭证时使用此配置文件。 MCP仅公开`createRegistration`以启动 - SMS验证，密码设置和API凭证生成都在用户点击的页面中发生。 代理不应尝试通过API使用SMS代码; 它属于用户的浏览器流程。
```sh
BW_MCP_TOOLS=createRegistration
```
## 使用服务器
下面您将找到有关将我们的MCP服务器与不同的常见AI代理一起使用的说明，以及有关在本地运行服务器的说明。 对于与AI代理一起使用，建议使用`uv`和环境变量的组合来启动和配置服务器。
### Goose CLI
1. 安装[Goose CLI](https://block.github.io/goose/docs/getting-started/installation/)
- 我们建议配置Goose使用`Allow Mode`。 这将需要用户在Goose调用工具之前获得批准，这可以防止Goose意外采取不想要的行动。
2. 将Bandwidth MCP服务器添加为命令行扩展
```shell
goose configure
```
然后按照下面的示例提示进行。
```shell
┌ goose-configure
│
◇ 您想配置什么？
│ 添加扩展
│
◇ 您想添加什么类型的扩展？
│ 命令行扩展
│
◇ 您想调用此扩展？
│ bw-mcp-server
│
◇ 应该运行什么命令？
│ uvx --from /path/to/mcp-server start
```
> **_注意：_** 如果您使用Goose配置环境变量，它将优先于您的系统环境变量。
### Cursor
1. 安装[Cursor](https://cursor.com/downloads)
2. 更新您的`.cursor/mcp.json`文件以包含以下对象
```json
{
"mcpServers": {
"bw-mcp-server": {
"command":"uvx",
"args": ["--from", "/path/to/mcp-server", "start"],
"env": {
"BW_CLIENT_ID": "<插入bw-client-id>",
"BW_CLIENT_SECRET": "<插入bw-client-secret>",
"BW_MCP_TOOLS": "工具，要启用",
"BW_MCP_EXCLUDE_TOOLS": "工具，要排除",
}
}
}
}
```
### VSCode（Copilot）
1. 在VSCode中，打开命令面板并搜索`MCP: 添加服务器`。
2. 选择`命令（stdio）`，然后输入启动服务器的完整命令。（例如下面）
```shell
uvx --from /path/to/mcp-server start
```
3. 为服务器选择一个名称（例如`bw-mcp-server`），并选择是否要在全局或当前工作区中启用它。
4. 您可以通过打开VSCode提供的`mcp.json`文件来配置环境变量，如下面的示例所示。
```json
{
"servers": {
"bw-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "/path/to/mcp-server", "start"],
"env": {
"BW_CLIENT_ID": "<插入bw-client-id>",
"BW_CLIENT_SECRET": "<插入bw-client-secret>",
"BW_MCP_TOOLS": "工具，要启用",
"BW_MCP_EXCLUDE_TOOLS": "工具，要排除",
}
}
},
"inputs": []
}
```
> **_注意：_** 您可能需要确保在VSCode中启用了MCP服务器才能开始使用服务器。有关更多信息，请参见[官方指南](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)。
### Claude Desktop
1. 安装[Claude Desktop](https://claude.ai/download)
2. 编辑您的`claude_desktop_config.json`以包含以下对象
```json
{
"mcpServers": {
"Bandwidth": {
"command": "uvx",
"args": ["--from", "/path/to/mcp-server", "start"],
"env": {
"BW_CLIENT_ID": "<插入bw-client-id>",
"BW_CLIENT_SECRET": "<插入bw-client-secret>",
"BW_MCP_TOOLS": "工具，要启用",
"BW_MCP_EXCLUDE_TOOLS": "工具，要排除",
}
}
}
}
```
> **_注意：_** 我们注意到Claude无法看到MCP资源的问题。这可能需要您手动输入通常包含在我们的配置资源中的一些工具参数。
### 独立运行服务器
MCP服务器可以使用原生Python或uv本地运行。
以这种方式运行时，所有环境变量都必须在您的系统环境中设置。
#### 使用原生Python运行
在本地使用Python[虚拟环境](https://docs.python.org/3/library/venv.html)运行服务器需要同时安装[Python](https://www.python.org/downloads/)和[pip](https://pip.pypa.io/en/stable/getting-started/)。
安装完成后，使用以下命令创建虚拟环境：
```sh
python -m venv .venv
```
然后激活并使用其依赖项安装项目。
```sh
source .venv/bin/activate
pip install .
```
在虚拟环境中安装所有软件包后，您可以使用以下命令在本地运行服务器：
```sh
python src/app.py
```
#### 使用uv运行
确保您已安装[uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation)，
然后可以通过从此存储库的根目录运行以下命令启动服务器。
```sh
uvx --from ./ start
```
## 托管模式
通过HTTP运行服务器以启用远程访问和Webhook回调：
```bash
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
```
### 本地回调隧道（仅限开发）
语音和消息回调需要Bandwidth通过公共URL访问您的服务器。
在生产环境中，您可以设置`BW_MCP_BASE_URL`。
对于本地开发，设置`BW_MCP_DEV_TUNNEL=1`，服务器将打开一个短暂的[`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)隧道，
使用生成的`*.trycloudflare.com`URL作为`BW_MCP_BASE_URL`，
并自动将语音应用的回调连接到它 - 不需要ngrok。
```bash
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
```
需要`cloudflared`在您的PATH上（在macOS上为`brew install cloudflared`）。
如果它丢失，服务器会记录警告并在没有隧道的情况下启动。
这仅用于**开发和测试** - 生产部署应使用`BW_MCP_BASE_URL`通过真正的托管地址。
隧道在未设置`BW_MCP_DEV_TUNNEL`时永远不会启动。
### 工具配置文件
使用命名预设减少上下文窗口压力：
```bash
BW_MCP_PROFILE=messaging # 仅限SMS/MMS工具
BW_MCP_PROFILE=voice # 语音 + BXML工具
BW_MCP_PROFILE=onboarding # 帐户创建
BW_MCP_PROFILE=lookup # 号码智能
BW_MCP_PROFILE=messaging,voice # 组合配置文件
```
通过`BW_MCP_PROFILE`环境变量或`--profile` CLI标志设置配置文件。
使用`BW_MCP_TOOLS`覆盖特定的工具名称。
## 工具列表
工具被分组到配置文件中，以镜像您将使用服务器的工作流程。
加载单个配置文件可以保持代理的上下文较小。
完整的代理参考 - 包括身份验证模型，错误代码和异步调用的“信任 nothing”指导 - 位于[`src/specs/AGENTS.md`](src/specs/AGENTS.md)。
默认工具集是`voice` + `messaging` + `lookup`（以及始终加载的`setCredentials` / `clearCredentials`）。
使用`BW_MCP_PROFILE`，`BW_MCP_TOOLS`或`BW_MCP_EXCLUDE_TOOLS`覆盖。
### 会话管理（始终加载）
- `setCredentials` — 身份验证会话（仅限stdio传输）
- `clearCredentials` — 注销会话
### 配置文件：`onboarding`（无需身份验证）
启动新的Bandwidth Build帐户。仅公开一个工具 - SMS验证，密码设置和API凭证生成都在用户的浏览器中发生。代理在启动后移交。
- `createRegistration` — 提交联系信息；Bandwidth然后发送SMS验证码并通过电子邮件发送密码设置链接
### 配置文件：`voice`
- `listApplications` / `createApplication` — 查找或创建语音应用
- `listPhoneNumbers` — 查找帐户中的号码
- `createCall` — 发起外呼
- `getCallState` — 读取当前呼叫状态（始终在`createCall`后轮询）
- `listCalls` — 列出呼叫事件并过滤
- `updateCall` / `updateCallBxml` — 重定向，挂断或替换BXML
- `generateBXML` — 从动词列表构建有效的BXML
- `respondToCallback` — 为活动回调排队BXML响应（先到先得）
- `getCallbackEvents` — 读取最近的语音/消息回调事件
- `configureCallbacks` — 将应用程序的Webhook URL指向此服务器
### 配置文件：`messaging`
- `createMessage` — 发送SMS / MMS
- `listMessages` — 查询消息历史记录
- `getInboundMessages` — 读取此服务器捕获的入站消息
- `listMedia` / `getMedia` / `uploadMedia` / `deleteMedia` — 管理MMS媒体
- `configureCallbacks` — 将应用程序的回调指向此服务器
### 配置文件：`lookup`
- `createSyncLookup` — 用于小输入集的一次性查找
- `createAsyncBulkLookup` — 启动批量查找
- `getAsyncBulkLookup` — 轮询批量查找
### 配置文件：`recordings`
- `listCallRecordings` / `getCallRecording` — 列出/检查录音
- `downloadCallRecording` — 下载媒体
- `deleteRecording` — 删除录音
- `transcribeCallRecording` / `getRecordingTranscription` — 请求和读取转录
参见[`src/specs/AGENTS.md`](src/specs/AGENTS.md)获取参数级指导，轮询模式和服务器在失败时返回的结构化错误形状。
