Webex MCP

Webex MCP

Webex的本地stdio MCP服务器，作为Bun第一个独立仓库构建。

它揭示了什么

• 用户范围和机器人范围的标识
• 房间列表和房间查找
• 房间分辨率从 webexteams:// 链接或UUID
• 基于轻量级模糊排序的房间搜索
• 通过Node支持的SDK助手读取实验室状态工具
• 用于键入状态、反应、线程和对话状态的实验性内部对话工具
• 用户范围的会议列表和资产检查
• 用户范围的会议记录列表
• 用户范围的会议记录列表、下载和片段搜索
• 本地会议记录/录音记录索引和搜索
• 用于缓存房间/消息搜索的本地SQLite索引
• 由本地SQLite索引支持的缓存消息搜索
• 用于最近空间或一个房间历史记录的房间同步工具
• 人员搜索和人员查找
• 会员列表、添加和删除
• 团队和团队成员
• 邮件列表、查找、发送、更新和删除
• 显式线程回复列表
• 附件操作提交和查找
• webhook创建、列表、更新和删除
• 跨最近房间历史记录的邮件搜索
• 直接发送 toPersonEmail 或 toPersonId
• 原始HTML消息发送
• 自适应卡消息发送
• 以工程为重点的丰富消息助手
• 通过身份验证的fetch下载文件
• 房间中的最新附件查找
• 文本、pdf、docx、pptx和xlsx的本地文本提取

运行时

• 主运行时：Bun
• 包管理器：Bun
• 文档提取助手： python3
• 文档提取Python包： pypdf, python-pptx, openpyxl
• 用于读取状态工具的实验SDK助手： node

身份模型

• actor: "user" 用途 WEBEX_USER_TOKEN 或OAuth刷新文件
• actor: "bot" 用途 WEBEX_BOT_TOKEN
• actor: "auto" 偏爱 user 当它被配置并且有效时；它只会倒退到 bot 未配置用户身份验证时

这很重要，因为：

• 用户参与者作为授权集成的OAuth用户进行操作
• bot参与者作为配置的bot帐户运行
• 这两个参与者仍然仅限于其令牌可用的房间、范围和成员资格

文件

send_message 支持：

• filePaths：当从磁盘上传本地文件时 WEBEX_MCP_ENABLE_LOCAL_FILES=true
• fileUrls：传递到Webex的远程URL

extract_message_files 下载消息上的每个文件URL，并可选择提取文本。 extract_local_file_text 后面也有门 WEBEX_MCP_ENABLE_LOCAL_FILES=true 和 WEBEX_MCP_LOCAL_FILE_ROOTS.

丰富的发送表面：

• send_message 支持 text, markdown, html、托管文件URL、本地文件上传和原始自适应卡 attachments
• send_engineering_message 构建结构化工程更新 markdown, html，或自适应卡

写安全

此MCP硬块写入大型组室：

• send_message 和 update_message 因任何原因被拒绝 group 20人或以上的房间
• 这是一个代码级策略，而不是提示级约定
• 改变这种行为需要更改代码

本地索引

MCP可以将房间和消息历史缓存到本地SQLite数据库中，并使用该缓存 search_messages.

推荐流量：

1. 跑 sync_all_rooms 一次缓存所有可访问的房间元数据。
2. 使用 search_rooms 和 resolve_space 与那套缓存的房间相比。
3. 跑 sync_recent_rooms 缓存您最活跃的房间消息。
4. 使用 search_messages 用于索引本地查找。
5. 跑 sync_room_history 当你想要一个房间有更深入的历史时。

笔记：

• 缓存是参与者范围的，因此bot可见数据和用户可见数据保持分离
• 附件文件名通过消息记录进行索引；附件正文仍然可以通过提取工具选择加入
• 本地索引功能使用Bun的内置SQLite
• search_messages 和 search_rooms 故意严格：如果缓存丢失，它们会失败，并告诉您要运行哪个同步工具

网络钩子

此MCP可以管理Webex webhook对象：

• list_webhooks
• get_webhook
• create_webhook
• update_webhook
• delete_webhook

重要提示：

• 此独立MCP不承载webhook接收器
• webhook工具是仅用于远程Webex webhook注册的CRUD助手

实验读取状态

这些工具使用小型Node-backed SDK帮助程序，因为公共Webex REST API不公开 lastSeenDate 或阅读收据：

• list_rooms_with_read_status
• get_room_with_read_status
• mark_message_seen

笔记：

• 这些工具仅供用户使用，而不仅仅是机器人
• 如果SDK无法访问底层内部Webex服务，它们会快速失败并超时
• 主MCP服务器仍在Bun下运行；只有助手使用 node

实验性内部对话

这些工具还使用Node支持的SDK助手，因为它们是内部对话界面 与公共REST API相比：

• update_typing_status
• list_threads
• add_reaction
• delete_reaction
• set_conversation_state

笔记：

• 这些只是用户，而不是机器人
• 他们使用内部SDK路径，如果所需的内部Webex服务不可用，可能会超时
• list_threads 是房间范围的，从按以下方式分组的公共房间消息中派生线程根 parentId
• list_thread_replies 不同之处在于：它是一个普通的MCP包装器 list_messages(parentId=...)

会议和录音

这些工具使用带有用户OAuth令牌的Webex会议API：

• create_meeting
• list_recordings
• list_meetings
• list_meeting_participants
• get_meeting
• update_meeting
• delete_meeting
• get_meeting_preferences
• list_meeting_preference_sites
• get_meeting_audio_preferences
• update_meeting_audio_preferences
• get_meeting_scheduling_preferences
• update_meeting_scheduling_preferences
• get_personal_meeting_room_preferences
• update_personal_meeting_room_preferences
• get_meeting_controls
• update_meeting_controls
• inspect_meeting_assets
• get_recording
• get_recording_transcript
• list_meeting_transcripts
• get_meeting_transcript
• search_meeting_transcript
• sync_recent_meeting_content
• search_meeting_content

笔记：

• 它们只是用户，而不仅仅是机器人
• 它们要求用户满足您配置的OAuth设置中存在的OAuth范围
• 会议CRUD使用正常 /meetings API，并已根据当前OAuth令牌进行了实时验证
• 最重要的 meetingPreferences 是只读的；可写首选项曲面是 audio, schedulingOptions，以及 personalMeetingRoom
• update_meeting_audio_preferences 自动规范空电话号码，以便Webex API接受有效负载
• 会议控件是一个实时会议界面；MCP公开原始控件对象，但资源仅在Webex公开时存在 /meetings/{meetingId}/controls
• list_meeting_participants 当Webex向OAuth用户提供参与者数据时，显示实际的会议出席行
• get_recording_transcript 使用录制详细信息响应所公开的临时转录链接（如果存在）
• get_meeting_transcript 下载 txt 或 vtt 直接从成绩单下载链接获取内容
• sync_recent_meeting_content 将来自转录端点的转录文本和转录链接记录到本地SQLite索引中

Webex呼叫CDR

这些工具使用用户级Webex Calling API：

• list_active_calls
• list_user_call_history

笔记：

• 它们只是用户，而不仅仅是机器人
• 它们需要用户级调用范围，例如 spark:calls_read, spark:xsi，有时 spark:webrtc_calling
• list_active_calls 电话 /telephony/calls 并且仅返回当前活动的呼叫控制状态
• list_user_call_history 电话 /telephony/calls/history；它可以计算最近未接/接听/拨打的电话，但它不是CDR，可能会省略持续时间

这些工具使用Webex呼叫详细呼叫历史API：

• list_call_detail_records
• list_live_call_detail_records

笔记：

• 它们只是用户，而不仅仅是机器人
• 他们需要 spark-admin:calling_cdr_read 关于OAuth授权
• 身份验证用户还必须具有Control Hub角色 Webex Calling Detailed Call History API access
• list_call_detail_records 电话 analytics-calling.webexapis.com/v1/cdr_feed 每次请求限制为12小时
• list_live_call_detail_records 电话 analytics-calling.webexapis.com/v1/cdr_stream 每次请求限制为2小时
• 如果Webex返回区域端点提示，请设置 WEBEX_CALLING_CDR_BASE_URL 或通过 baseUrl 到工具
• spark-admin:locations_read 对于位置元数据是可选的，但除非集成在Webex开发人员门户中选择了该范围，否则不要请求它

安装

cd webex-mcp
bun install
python3 -m pip install -r requirements.txt

Webex应用程序设置

如果你想让这个仓库作为一个独立的集成工作：

1. 在以下位置创建Webex集成 https://developer.webex.com/my-apps.
2. 添加一个与您的env文件匹配的重定向URI。

例子： http://localhost:8765/oauth/callback

1. 启用中的范围 .env.example / WEBEX_OAUTH_SCOPES.
2. 复制 .env.example 到 .env.local 并填写：

- WEBEX_CLIENT_ID - WEBEX_CLIENT_SECRET - WEBEX_REDIRECT_URI

1. 运行OAuth登录帮助程序一次。

OAuth和Reauth

独立仓库现在包括一个本地OAuth助手：

cd webex-mcp
bun run auth:login

它的作用：

• 使用以下命令启动一个小型本地回调侦听器 WEBEX_REDIRECT_URI
• 在浏览器中打开Webex授权URL
• 将返回的代码替换为令牌
• 写入由配置的令牌文件 WEBEX_OAUTH_TOKEN_FILE

有用的命令：

bun run auth:status
bun run auth:refresh
bun run auth:clear

笔记：

• 正常访问令牌到期不需要完全重新认证； server.mjs 已通过存储的刷新 refresh_token
• 你通常只需要 auth:login 同样，当范围发生变化、刷新令牌过期或授权被撤销时
• 如果您更喜欢另一个env文件，请使用 bun oauth.mjs --env-file /abs/path/.env.local
• 当 --env-file 传递后，该文件对Bun的自动加载环境变量具有权威性

发布安全

在发布或共享此仓库之前：

• 仅在忽略的env文件中保留真实凭据，例如 .env.local
• 仅在由配置的令牌文件中保留OAuth授权 WEBEX_OAUTH_TOKEN_FILE
• 不要提交本地状态目录，因为它可以包含缓存的文件室历史记录、下载和SQLite索引
• 默认情况下，本地文件访问是故意关闭的；只能用一个紧的 WEBEX_MCP_LOCAL_FILE_ROOTS 允许名单
• 如果您将README示例改编为本地环境，请查看这些示例

此仓库已经忽略了：

• .env* 除了 .env.example
• .data/
• node_modules/

跑

如果您正在重用另一个应用程序的env文件：

cd webex-mcp
bun server.mjs --env-file /path/to/other/.env.local

如果你想让这个仓库拥有自己的env文件：

cd webex-mcp
cp .env.example .env.local
bun server.mjs --env-file .env.local

独立流量：

cd webex-mcp
cp .env.example .env.local
bun run auth:login
bun run start

Codex配置

将此添加到 ~/.codex/config.toml:

[mcp_servers.webex]
command = "bun"
args = ["/absolute/path/to/webex-mcp/server.mjs", "--env-file", "/absolute/path/to/webex-mcp/.env.local"]

然后重新启动Codex，使其加载新的MCP服务器。

Claude代码配置

如果您希望Claude Code使用此相同的本地MCP而不是托管的Webex端点， 指向其插件或 .mcp.json 同一stdio服务器上的条目：

{
  "mcpServers": {
    "webex": {
      "type": "stdio",
      "command": "bun",
      "args": [
        "/absolute/path/to/webex-mcp/server.mjs",
        "--env-file",
        "/absolute/path/to/webex-mcp/.env.local"
      ]
    }
  }
}

如果Claude指向远程HTTP MCP，而Codex指向此本地仓库，则在此仓库中修复 只会影响Codex。

工具架构兼容性

一些MCP客户端拒绝工具参数模式，除非顶级 inputSchema 是平原 type: "object" 没有顶级 allOf, anyOf, oneOf, enum，或 not.

此仓库现在在加载时和 bun run check.

当工具需要有条件的要求时，例如“提供 meetingId 或 recordingId“，保持 代码中的运行时保护，并在相关属性描述中描述约束 使用顶级模式组合子。

有用的环境变量

• WEBEX_OAUTH_TOKEN_FILE 覆盖令牌文件位置。默认情况下，它使用每个用户的状态目录。
• WEBEX_MCP_DOWNLOAD_DIR 覆盖文件工具的下载目录。默认情况下，它使用每个用户的状态目录。
• WEBEX_MCP_INDEX_DB 覆盖SQLite索引路径。默认情况下，它使用每个用户的状态目录。
• WEBEX_MCP_ENABLE_LOCAL_FILES=true 使能够 filePaths 上传和 extract_local_file_text.
• WEBEX_MCP_LOCAL_FILE_ROOTS 是一个 :-分离的分配列表用于本地文件访问。