GitHub - Kashyap-AI-ML-Solutions/webex-messaging-mcp-server: A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to Cisco Webex messaging capabilities. (original) (raw)

MseeP.ai Security Assessment Badge

Webex MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to Cisco Webex messaging capabilities.

Webex Server MCP server

Overview

This MCP server enables AI assistants to interact with Webex messaging through 52 different tools covering:

Features

Quick Start

Prerequisites

Token Renewal

Webex Bearer tokens are short-lived. Your current token expires in 12 hours. To renew:

  1. Visit: https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms
  2. Login with your email
  3. Copy the new bearer token from your profile
  4. Update environment variable "WEBEX_PUBLIC_WORKSPACE_API_KEY" with new token (remove "Bearer " prefix)

Installation

  1. Clone and install dependencies:
    git clone
    cd webex-messaging-mcp-server
    npm install
  2. Configure environment:
    cp .env.example .env

Edit .env with your Webex API token

  1. Test the server:

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

🔍 Tool Discovery

The server includes comprehensive tool discovery capabilities:

Tool Discovery Commands

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

Tool Manifest

The tools-manifest.json file provides:

Tool Organization

Tools are organized by functionality:

Docker Usage

  1. Build and run:
    docker build -t webex-mcp-server .
    docker run -i --rm --env-file .env webex-mcp-server
  2. Using docker-compose:
    docker-compose up webex-mcp-server

Configuration

Environment Variables

Variable Required Description Default
WEBEX_PUBLIC_WORKSPACE_API_KEY Yes Webex API token (without "Bearer " prefix) -
WEBEX_API_BASE_URL No Webex API base URL https://webexapis.com/v1
WEBEX_USER_EMAIL No Your Webex email (for reference) -
PORT No Port for HTTP mode 3001
MCP_MODE No Transport mode (stdio or http) stdio

Getting a Webex API Token

  1. Visit developer.webex.com
  2. Sign in with your Cisco/Webex account
  3. Copy the bearer token from the API documentation
  4. Important: Remove the "Bearer " prefix when adding to your .env file

MCP Client Integration

Claude Desktop (STDIO Mode)

Add to your Claude Desktop configuration:

{ "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": "your.email@company.com", "WEBEX_API_BASE_URL": "https://webexapis.com/v1", "WEBEX_PUBLIC_WORKSPACE_API_KEY": "your_token_here" } } } }

HTTP Mode Integration

For HTTP-based MCP clients, start the server in HTTP mode:

Start HTTP server

npm run start:http

Server endpoints:

Health check: http://localhost:3001/health

MCP endpoint: http://localhost:3001/mcp

The server supports MCP 2025-06-18 protocol with StreamableHTTP transport, including:

Other MCP Clients

For STDIO mode:

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

For HTTP mode:

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

Available Tools

Core Messaging

Room Management

Team Operations

Membership Management

People & Directory

Webhooks & Events

Enterprise Features

Transport Modes

STDIO Mode (Default)

The default transport mode for MCP clients like Claude Desktop:

Start in STDIO mode

node mcpServer.js

or

npm start

HTTP Mode (StreamableHTTP)

HTTP-based transport supporting MCP 2025-06-18 protocol:

Start in HTTP mode

npm run start:http

or

node mcpServer.js --http

HTTP Mode Features:

Environment Variables:

Smithery Integration

The server is configured for automatic deployment via Smithery with HTTP runtime:

smithery.yaml

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

Deploy with: smithery deploy

Development

Project Structure

├── 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

Adding New Tools

  1. Create a new tool file in tools/webex-public-workspace/webex-messaging/
  2. Follow the existing tool pattern with proper imports
  3. Add the tool path to tools/paths.js
  4. Test with node index.js tools

Security

Testing

🧪 Comprehensive Test Suite

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

🔒 Pre-Commit Quality Gates

Automatic quality assurance using Husky pre-commit hooks:

Automatically runs on git commit:

🚀 Running pre-commit validation... 🔍 Checking code quality and running 118 unit tests... ✅ All validations passed! Commit proceeding...

What's validated:

See tests/README.md for detailed testing documentation.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Tests run automatically on commit via pre-commit hooks
  5. Ensure all 118 tests pass
  6. Submit a pull request

License

MIT License - see LICENSE file for details

Support