MCP Webex呼叫服务器
用于与Webex呼叫API交互的MCP（模型上下文协议）服务器。此服务器使您能够通过与Claude Desktop等人工智能助手的自然语言对话，查询Webex Calling数据并在Webex组织内执行管理功能。
什么是MCP？
MCP（模型上下文协议）是一种标准化协议，允许AI助手安全地连接到外部服务和数据源。MCP服务器不是手动导航API或编写脚本，而是将功能作为AI助手可以理解和代表您使用的工具。
为什么使用MCP进行Webex呼叫？
通过传统方法管理Webex呼叫可能很耗时：
- 手动API调用：需要理解复杂的API文档并编写代码
- Web界面：对于批量操作或重复性任务，点击可能会很慢
- 脚本：需要为每个用例编写、维护和更新
使用MCP，您可以：
- 用自然语言提问： *“我们配置了哪些呼叫队列？”*
- 无需编写代码即可获得即时答案
- 通过对话执行管理任务： *“将电话号码X分配给用户Y”*
- 从Webex组织访问实时数据
- 通过AI助手自动化工作流程
这使得任何人都可以访问Webex Calling管理，无论其技术专长如何。
它能做什么？
MCP Webex呼叫服务器提供 85+工具 分为以下几类：
数据检索
- 查询Webex Calling用户、位置和组织
- 检索呼叫队列信息、自动助理、搜索组和中继组
- 获取设备和电话号码信息
- 查询通话历史和详细通话记录
- 列出许可证和用户分配
用户管理
- 创建、更新和删除用户
- 管理用户分机和电话号码
- 分配和取消分配许可证
- 按姓名、电子邮件或分机号搜索用户
位置管理
- 创建、更新和删除位置
- 管理位置设置和配置
- 列出组织中的所有位置
呼叫队列管理
- 创建、更新和删除呼叫队列
- 管理队列成员和设置
- 配置队列路由和溢出
汽车服务员管理
- 创建、更新和删除自动助理
- 配置菜单选项和问候语
- 管理营业时间和时间表
亨特集团管理
- 创建、更新和删除狩猎组
- 配置狩猎组路由策略
- 管理组成员
设备管理
- 列出和管理设备
- 将设备与用户关联
- 获取设备详细信息和配置
- 生成设备注册的激活码（无需MAC地址）
- 按MAC地址和型号创建/配置设备
报告和分析
- 获取通话详细记录（CDR）
- 计算通话统计数据（分钟、秒、通话次数）
- 检索呼叫分析和指标
- 为用户、地点或时间段生成报告
语音邮件管理
- 配置语音邮件设置
- 管理语音邮件问候和通知
Webhook和事件管理
- 列出和管理Webhook
- 配置事件订阅
- 处理实时通知
用例
- 快速查询：“我们配置了哪些呼叫队列？”或“显示用户的所有设备”john@example.com"
- 管理任务：“将电话号码X分配给用户Y”或“创建一个名为“支持”的新呼叫队列”
- 设备配置：“为用户生成激活码john@example.com或“创建MAC地址为AABBCCDDEEFF的设备”
- 分析和报告：“获取上个月的呼叫分析”或“显示队列性能指标”
- 故障排除：“用户X的通话设置是什么？”或“列出位置Y的所有设备”
- 批量操作：“更新位置X中所有用户的扩展名”或“列出组织中的所有许可证”
设备管理
服务器提供两种设备配置方法：
激活码方法（推荐）
配置设备的最简单方法是生成激活码。此方法只需要用户的个人ID，不需要MAC地址：
- 生成激活码 对于用户
- 将代码提供给用户 -他们在设置过程中在设备上输入它
- 设备会自动注册并与他们的帐户关联
例子：
- *“为用户生成激活码john@example.com"*
激活码在设定的时间段（通常是几个月）后过期，因此用户有足够的时间来设置他们的设备。
MAC地址方法
对于预先知道MAC地址的设备，您可以直接创建设备条目：
- 创建设备 使用MAC地址和型号
- 关联设备 与用户（可选，稍后可以完成）
- 设备将准备好注册
例子：
- *“创建MAC地址为AABBCCDDEEFF、型号为Cisco 8841的设备”*
MAC地址格式：
- 接受12位十六进制格式（例如。，
AABBCCDDEEFF) - 还接受冒号或破折号分隔符（例如。，
AA:BB:CC:DD:EE:FF或AA-BB-CC-DD-EE-FF) - 自动标准化为大写格式
入门指南
先决条件
- Python 3.9或更高版本
- Webex访问令牌（请参阅 配置 在......下面
- Claude Desktop（可选，用于AI助手集成）
安装
- 克隆存储库：
git clone https://github.com/lutztalk/mcp-webexcalling.git
cd mcp-webexcalling- 创建虚拟环境：
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项：
pip install -r requirements.txt- 安装软件包：
pip install -e .配置
获取Webex访问令牌
- 首选 developer.webex.com
- 使用您的Webex帐户登录
- 点击您的个人资料→ 个人访问令牌
- 点击 生成令牌
- 复制生成的令牌（只显示一次）
注： 个人访问令牌在12小时后过期。有关生产用途，请参阅 生产设置 在......下面
设置环境变量
创建一个 .env 项目根目录中的文件：
WEBEX_ACCESS_TOKEN=your_token_here
WEBEX_BASE_URL=https://webexapis.com/v1安全说明： 永远不要承诺你的 .env 文件到版本控制。它已经在里面了 .gitignore.
运行服务器
服务器可以直接运行：
python -m mcp_webexcalling.server或与Claude Desktop一起使用（请参阅 连接到克劳德桌面 在......下面
连接到克劳德桌面
按照以下分步说明将MCP Webex Calling服务器连接到Claude Desktop。
先决条件
- 已安装Python 3.9+
- 已安装Claude Desktop
- Webex访问令牌（请参阅 配置 以上）
第一步：找到你的Python路径
macOS/Linux：
which python3
# or
which pythonWindows（PowerShell）：
where python注意路径（例如。， /opt/homebrew/bin/python3.12 或 C:\Python312\python.exe).
步骤2：找到Claude桌面配置
macOS：
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux：
~/.config/Claude/claude_desktop_config.json窗户：
%APPDATA%\Claude\claude_desktop_config.json步骤3：配置Claude桌面
编辑配置文件并添加MCP服务器配置：
{
"mcpServers": {
"webex-calling": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "mcp_webexcalling.server"],
"cwd": "/path/to/mcp-webexcalling",
"env": {
"WEBEX_ACCESS_TOKEN": "your_token_here",
"WEBEX_BASE_URL": "https://webexapis.com/v1"
}
}
}
}重要提示：
- 替换
/path/to/your/venv/bin/python使用步骤1中的实际Python路径 - 替换
/path/to/mcp-webexcalling这个项目的实际路径 - 替换
your_token_here使用您的Webex访问令牌
步骤4:重新启动克劳德桌面
关闭并重新打开Claude Desktop以加载新配置。
步骤5：验证连接
打开克劳德桌面，检查服务器是否已连接。您应该在MCP服务器列表中看到“webex calling”。
故障排除
服务器已断开连接：
- 验证Python路径是否正确并指向您的虚拟环境
- 检查一下
cwd路径正确 - 确保
.env文件具有正确的令牌（或使用env配置中的部分） - 检查Claude Desktop日志中的错误消息
导入错误：
- 请确保您已安装该软件包：
pip install -e . - 验证是否安装了所有依赖项：
pip install -r requirements.txt
权限错误：
- 确保Python可执行文件具有执行权限
- 检查项目目录是否具有读取权限
生产设置
个人访问令牌在12小时后过期，不适合生产使用。本节介绍如何设置永久性Webex Bot或集成，以进行长期、生产就绪的身份验证。
选项1:Webex Bot（推荐）
- 首选 developer.webex.com
- 导航至 我的应用 → 机器人
- 点击 创建Bot
- 填写机器人详细信息：
- 名字：您的机器人名称 - 用户名：唯一的机器人用户名（例如。， mcp-webex-calling-bot) - 图标：可选的机器人图标
- 点击 添加机器人
- 复制 Bot访问令牌 （保持安全！）
- 将机器人添加到Webex空间并在其中运行
- 在您的账户中使用bot代币
.env文件：
WEBEX_ACCESS_TOKEN=your_bot_token_here优点：
- 令牌永不过期
- 可以分配给特定空间
- 易于管理和撤销
选项2:Webex集成
- 首选 developer.webex.com
- 导航至 我的应用 → 集成
- 点击 创建集成
- 选择 Webex呼叫 集成类型
- 填写所需的OAuth作用域：
- spark-admin:people_read - spark-admin:people_write - spark-admin:devices_read - spark-admin:devices_write - spark-admin:telephony_config_read - spark-admin:telephony_config_write
- 完成OAuth流程以获取刷新令牌
- 在应用程序中使用集成凭据
优点：
- 更精细的权限
- 更适合企业部署
- 支持OAuth刷新令牌
GitHub操作集成：Webex通知
使用GitHub Actions将代码推送到主分支时，向Webex空间设置自动通知。
设置
- 创建Webex Bot （参见 生产设置 以上）
- 获取Bot令牌和房间ID：
- 机器人令牌：来自机器人创建页面 - 房间ID：右键单击Webex空间→ 复制链接 → 从URL中提取房间ID
- 添加GitHub机密：
- 转到您的存储库→ 设置 → 秘密和变量 → 行动 - 添加密码： WEBEX_BOT_TOKEN （你的机器人代币） - 添加密码： WEBEX_ROOM_ID （您的房间ID）
- 工作流已配置 在
.github/workflows/webex-notifications.yml
当代码被推送到时，工作流将自动发送通知 main.
可用工具
服务器提供 85+MCP工具 按类别组织。查看完整列表 它能做什么？ 上面的部分。
示例用法
通过克劳德桌面
连接后，您可以提出以下问题：
- *“显示组织中的所有呼叫队列”*
- *“获取过去24小时的通话统计数据”*
- *“列出位置X的所有用户”*
- *“创建一个名为Support的新呼叫队列”*
- *“将电话号码+1234567890分配给用户john@example.com"*
- *“为用户生成激活码john@example.com"*
- *“创建MAC地址为AABBCCDDEEFF、型号为Cisco 8841的设备”*
API直接使用
你也可以直接在Python中使用客户端：
from mcp_webexcalling.webex_client import WebexClient
client = WebexClient(access_token="your_token")
# Get organization info
org_info = await client.get_organization_info()
# Get call queues
queues = await client.list_call_queues()
# Get call statistics
stats = await client.get_call_statistics_from_cdr(
start_time="2024-01-01T00:00:00Z",
end_time="2024-01-31T23:59:59Z"
)
# Generate activation code for a user
activation_code = await client.generate_activation_code(person_id="user_id_here")
print(f"Activation code: {activation_code['code']}")
print(f"Expires: {activation_code['expiryTime']}")
# Create a device by MAC address
device = await client.create_device_by_mac(
mac_address="AABBCCDDEEFF",
model="Cisco 8841"
)贡献
欢迎投稿！请随时提交拉取请求。
许可证
该项目根据MIT许可证获得许可。