Cisco Webex MCP Server

Webex MCP 服务

一个模型上下文协议（MCP）服务，为 AI 助手提供对 Cisco Webex 消息功能的全面访问。

从业务意图到 Webex 操作

AI Agent 可以将此服务用作协作操作层：将业务目标转化为一系列 Webex 操作，选择相关功能，并推动工作流直至完成。这些操作包括通知客户、组建事件响应空间、维护客户团队和空间、管理人员和成员资格、响应 Webex 事件，或连接企业内容与审批交互。

由于此服务将消息、空间、团队、成员资格、人员、webhook、事件、选项卡、附件操作和 ECM 文件夹作为可组合的 MCP 工具公开，Agent 可以围绕业务需求构建工作流，而不必受限于单一的硬编码自动化流程。

▶ 观看带声音的 15 秒讲解视频

使用 Claude 或 Codex 创建可用于发布的媒体

此讲解视频是通过 Agentic Media Harness 根据自然语言请求创建的。其 agentic-media 插件可将 Claude Code 或 Codex 转变为制作媒体的工作流：它会读取你的代码仓库、优化提示词、生成图像或视频、检查动画效果和脚本准确性、反复改进质量，并记录每条提示词、评分和花费。

只需安装一次插件，即可在编码 Agent 中创建了解代码仓库内容的产品视频、主视觉图、信息图和发布素材。

Claude Code

pip install "git+ssh://[email protected]/Kashyap-AI-ML-Solutions/agentic-media-harness.git#subdirectory=packages/amh"
claude plugin marketplace add Kashyap-AI-ML-Solutions/agentic-media-harness
claude plugin install agentic-media@agentic-media-harness
export GEMINI_API_KEY=your_key_here   # create + enable billing: https://aistudio.google.com/apikey

Codex CLI

pip install "git+ssh://[email protected]/Kashyap-AI-ML-Solutions/agentic-media-harness.git#subdirectory=packages/amh"
codex plugin marketplace add Kashyap-AI-ML-Solutions/agentic-media-harness
codex plugin add agentic-media@agentic-media-harness
export GEMINI_API_KEY=your_key_here   # optional for images; required for video

你也可以将 GEMINI_API_KEY=your_key 放在代码仓库的 .env 文件中。切勿提交该文件。

然后打开任意代码仓库并提出：

使用 media-video 技能，为此代码仓库创建一段简短的讲解视频。先阅读 README。我的预算是 $2.50。

概述

此 MCP 服务通过 52 种不同的工具，让 AI 助手能够与 Webex 消息功能交互，涵盖：

• 消息：发送、编辑、删除和检索消息
• 空间：创建和管理 Webex 空间
• 团队：团队创建和成员管理
• 人员：用户管理和目录操作
• Webhook：事件通知和集成
• 企业功能：ECM 文件夹、空间标签页和附件

功能

• ✅ 全面覆盖 Webex API：52 种工具，涵盖所有主要消息操作
• ✅ 支持 Docker：适用于生产环境的容器化
• ✅ 双传输模式：支持 STDIO 和 HTTP（StreamableHTTP）模式
• ✅ 适用于企业环境：支持 Cisco 企业身份验证
• ✅ 类型安全：完整的 TypeScript/JavaScript 实现，并提供恰当的错误处理
• ✅ 集中式配置：轻松管理令牌和端点

快速开始

前提条件

• Node.js 18+（推荐 20+）。警告：如果使用较低版本的 Node，fetch 将不可用。工具使用 fetch 发起 HTTP 调用。解决方法是修改工具，改用 node-fetch。确保已将 node-fetch 安装为依赖项，然后在每个工具文件中将其导入为 fetch。
• Docker（可选，用于容器化部署）
• 从 developer.webex.com 获取的 Webex API 令牌

令牌续期

Webex Bearer 令牌的有效期较短。当前令牌将在 12 小时后过期。续期步骤：

1. 访问：https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms
2. 使用你的电子邮件登录
3. 从个人资料中复制新的 Bearer 令牌
4. 使用新令牌更新环境变量 "WEBEX_PUBLIC_WORKSPACE_API_KEY"（删除 "Bearer " 前缀）

安装

1. 克隆并安装依赖项：

   git clone <repository-url>
   cd webex-messaging-mcp-server
   npm install
   

2. 配置环境：

   cp .env.example .env
   # Edit .env with your Webex API token
   

3. 测试服务：

   # List available tools
   node index.js tools
   
   # Discover tools with detailed analysis
   npm run discover-tools
   
   # Start MCP server (STDIO mode - default)
   node mcpServer.js
   
   # Start MCP server (HTTP mode)
   npm run start:http
   

🔍 工具发现

该服务包含全面的工具发现功能：

工具发现命令

# Human-readable tool analysis
npm run discover-tools

# JSON output for programmatic use
npm run discover-tools -- --json

# Filter tools by category
ENABLED_TOOLS=create_message,list_rooms npm run discover-tools

# Get help
npm run discover-tools -- --help

工具清单

tools-manifest.json 文件提供：

• 工具类别：消息、空间、团队、成员关系、人员、Webhook、企业
• 工具总数 52 种：全面覆盖 Webex 消息 API
• 环境配置：必需和可选变量
• 测试信息：覆盖范围和验证详情
• 迁移历史：MCP 协议升级文档

工具分类

工具按功能分类：

• 消息（6 种工具）：创建、列出、编辑和删除消息
• 空间（6 种工具）：空间管理和配置
• 团队（5 种工具）：团队创建和管理
• 成员关系（10 种工具）：空间和团队成员操作
• 人员（6 种工具）：用户资料和目录管理
• Webhook（7 种工具）：事件通知和 Webhook 管理
• 企业（12 种工具）：ECM 文件夹、空间标签页和附件

工具选择与行为元数据

全部 52 种工具都会通过 tools/list 发布 MCP 注释，以及简洁的选择和行为指引。原始用途说明和输入架构保持不变；追加的指引会指出最相近的同类工具、操作是读取还是更改 Webex 状态，以及 API 错误和速率限制的返回方式。

注释是提供给 MCP 客户端的描述性提示，不是授权控制。Webex 访问令牌和组织策略仍具有最终决定权。

Docker 用法

1. 构建并运行：

   docker build -t webex-mcp-server .
   docker run -i --rm --env-file .env webex-mcp-server
   

2. 使用 docker-compose：

   docker-compose up webex-mcp-server
   

配置

环境变量

变量	必需	描述	默认值
WEBEX_PUBLIC_WORKSPACE_API_KEY	是	Webex API 令牌（不带 "Bearer " 前缀）	-
WEBEX_API_BASE_URL	否	Webex API 基础 URL	https://webexapis.com/v1
WEBEX_USER_EMAIL	否	您的 Webex 邮箱（供参考）	-
PORT	否	HTTP 模式的端口	3001
MCP_MODE	否	传输模式（stdio 或 http）	stdio

获取 Webex API 令牌

1. 访问 developer.webex.com
2. 使用您的 Cisco/Webex 账户登录
3. 从 API 文档中复制 bearer 令牌
4. 重要：将令牌添加到 .env 文件时，请移除 "Bearer " 前缀

MCP 客户端集成

Claude Desktop（STDIO 模式）

添加到您的 Claude Desktop 配置中：

{
  "mcpServers": {
    "webex-messaging": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "WEBEX_PUBLIC_WORKSPACE_API_KEY",
        "-e",
        "WEBEX_USER_EMAIL",
        "-e",
        "WEBEX_API_BASE_URL",
        "webex-mcp-server"
      ],
      "env": {
        "WEBEX_USER_EMAIL": "[email protected]",
        "WEBEX_API_BASE_URL": "https://webexapis.com/v1",
        "WEBEX_PUBLIC_WORKSPACE_API_KEY": "your_token_here"
      }
    }
  }
}

HTTP 模式集成

对于基于 HTTP 的 MCP 客户端，请以 HTTP 模式启动服务：

# Start HTTP server
npm run start:http

# Server endpoints:
# Health check: http://localhost:3001/health
# MCP endpoint: http://localhost:3001/mcp

服务支持采用 StreamableHTTP 传输的 MCP 2025-11-25 协议，包括：

• 正确配置 CORS，并公开 mcp-session-id 标头
• 为有状态连接提供会话管理
• Server-Sent Events (SSE) 响应格式

其他 MCP 客户端

对于 STDIO 模式：

docker run -i --rm --env-file .env webex-mcp-server

对于 HTTP 模式：

docker run -p 3001:3001 --rm --env-file .env webex-mcp-server --http

可用工具

核心消息功能

• create_message - 向房间发送消息
• list_messages - 获取消息历史记录
• edit_message - 修改现有消息
• delete_message - 删除消息
• get_message_details - 获取特定消息的信息

房间管理

• create_room - 创建新的 Webex 空间
• list_rooms - 浏览可用房间
• get_room_details - 获取房间信息
• update_room - 修改房间设置
• delete_room - 删除房间

团队操作

• create_team - 创建团队
• list_teams - 浏览团队
• get_team_details - 获取团队信息
• update_team - 修改团队设置
• delete_team - 删除团队

成员资格管理

• create_membership - 将人员添加到房间
• list_memberships - 查看房间成员
• update_membership - 更改成员角色
• delete_membership - 移除成员
• create_team_membership - 添加团队成员
• list_team_memberships - 查看团队成员

人员与目录

• get_my_own_details - 获取您的个人资料
• list_people - 搜索用户
• get_person_details - 获取用户信息
• create_person - 添加新用户（仅限管理员）
• update_person - 修改用户详细信息
• delete_person - 移除用户（仅限管理员）

Webhook 与事件

• create_webhook - 设置事件通知
• list_webhooks - 管理 Webhook
• get_webhook_details - 获取 Webhook 信息
• update_webhook - 修改 Webhook
• delete_webhook - 移除 Webhook
• list_events - 获取活动日志
• get_event_details - 获取特定事件的信息

企业功能

• create_room_tab - 向房间添加标签页
• list_room_tabs - 查看房间标签页
• get_room_tab_details - 获取标签页信息
• update_room_tab - 修改标签页
• delete_room_tab - 移除标签页
• create_attachment_action - 处理表单提交
• get_attachment_action_details - 获取附件详细信息
• list_ecm_folder - 企业内容管理
• get_ecm_folder_details - 获取 ECM 文件夹详细信息
• create_ecm_folder - 创建 ECM 配置
• update_ecm_linked_folder - 修改 ECM 文件夹
• unlink_ecm_linked_folder - 移除 ECM 链接

传输模式

STDIO 模式（默认）

Claude Desktop 等 MCP 客户端的默认传输模式：

# Start in STDIO mode
node mcpServer.js
# or
npm start

HTTP 模式（StreamableHTTP）

基于 HTTP 的传输方式，支持 MCP 2025-11-25 协议：

# Start in HTTP mode
npm run start:http
# or
node mcpServer.js --http

HTTP 模式功能：

• 健康检查：GET http://localhost:3001/health
• MCP 端点：POST http://localhost:3001/mcp
• 会话管理：自动处理会话 ID
• CORS 支持：正确配置跨源请求
• 协议：MCP 2025-11-25，采用 StreamableHTTP 传输方式

环境变量：

• MCP_MODE=http - 强制使用 HTTP 模式
• PORT=3001 - 自定义端口（默认：3001）

Smithery 集成

服务器已配置为通过 Smithery 和 HTTP 运行时自动部署：

# smithery.yaml
runtime: "nodejs"
main: "mcpServer.js"
envMapping:
  webexApiKey: "WEBEX_PUBLIC_WORKSPACE_API_KEY"
  webexApiBaseUrl: "WEBEX_API_BASE_URL"

使用以下命令部署：smithery deploy

开发

项目结构

├── lib/
│   ├── tools.js           # Tool discovery and loading
│   └── webex-config.js    # Centralized API configuration
├── tools/
│   └── webex-public-workspace/webex-messaging/
│       ├── create-a-message.js
│       ├── list-messages.js
│       └── ... (50 more tools)
├── scripts/
│   └── update-webex-tools.js  # Automated tool updates
├── mcpServer.js           # Main MCP server
├── index.js              # CLI interface
├── Dockerfile             # Container configuration
└── docker-compose.yml    # Multi-container setup

添加新工具

1. 在 tools/webex-public-workspace/webex-messaging/ 中创建新的工具文件
2. 按照现有工具模式编写，并正确导入依赖
3. 将工具路径添加到 tools/paths.js
4. 使用 node index.js tools 进行测试

安全

• 非 root 容器：以用户 mcp（UID 1001）运行
• 多阶段构建：优化生产镜像
• 环境隔离：通过环境变量传递密钥
• 健康检查：支持容器监控

测试

🧪 全面的测试套件

• 118 项单元测试，分布在 53 个测试套件中
• 通过率 100%，覆盖全面
• 端到端测试覆盖 50 多个 API 端点
• 已验证 20 多项关键错误修复

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run tests locally (same as npm test)
npm run test:local

# Validate code quality + tests
npm run validate

🔒 提交前质量门禁

使用 Husky 提交前钩子自动进行质量保障：

# Automatically runs on git commit:
🚀 Running pre-commit validation...
🔍 Checking code quality and running 118 unit tests...
✅ All validations passed! Commit proceeding...

验证内容：

• JavaScript 语法检查
• 所有 118 项单元测试必须通过
• 代码质量标准
• API 实现正确性

详细测试文档请参阅 tests/README.md。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交时通过提交前钩子自动运行测试
5. 确保全部 118 项测试通过
6. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

支持

• 问题：通过 GitHub Issues 报告错误并提交功能请求
• 文档：详细设置说明请参阅 SETUP-COMPLETE.md
• 社区：加入 MCP 社区频道参与讨论