Webex Messaging MCP Server

🚀 Webex MCP Server

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

🚀 Quick Start

Prerequisites

• Node.js 18+ (20+ recommended). Warning: if you run with a lower version of Node, fetch won't be present. Tools use fetch to make HTTP calls. To work around this, you can modify the tools to use node-fetch instead. Make sure that node-fetch is installed as a dependency and then import it as fetch into each tool file.
• Docker (optional, for containerized deployment)
• Webex API token from developer.webex.com

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 <repository-url>
   cd webex-messaging-mcp-server
   npm install
   

2. Configure environment:

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

3. 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
   

✨ Features

• ✅ Complete Webex API Coverage: 52 tools covering all major messaging operations
• ✅ Docker Support: Production-ready containerization
• ✅ Dual Transport: Both STDIO and HTTP (StreamableHTTP) modes
• ✅ Enterprise Ready: Supports Cisco enterprise authentication
• ✅ Type Safe: Full TypeScript/JavaScript implementation with proper error handling
• ✅ Centralized Configuration: Easy token and endpoint management

📚 Documentation

Overview

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

• Messages: Send, edit, delete, and retrieve messages
• Rooms: Create and manage Webex spaces
• Teams: Team creation and membership management
• People: User management and directory operations
• Webhooks: Event notifications and integrations
• Enterprise Features: ECM folders, room tabs, and attachments

🔍 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 Categories: Messages, Rooms, Teams, Memberships, People, Webhooks, Enterprise
• 52 Total Tools: Complete Webex messaging API coverage
• Environment Configuration: Required and optional variables
• Testing Information: Coverage and validation details
• Migration History: MCP protocol upgrade documentation

Tool Organization

Tools are organized by functionality:

• Messages (6 tools): Create, list, edit, delete messages
• Rooms (6 tools): Room management and configuration
• Teams (5 tools): Team creation and management
• Memberships (10 tools): Room and team membership operations
• People (6 tools): User profile and directory management
• Webhooks (7 tools): Event notifications and webhook management
• Enterprise (12 tools): ECM folders, room tabs, attachments

Available Tools

Core Messaging

• create_message - Send messages to rooms
• list_messages - Retrieve message history
• edit_message - Modify existing messages
• delete_message - Remove messages
• get_message_details - Get specific message information

Room Management

• create_room - Create new Webex spaces
• list_rooms - Browse available rooms
• get_room_details - Get room information
• update_room - Modify room settings
• delete_room - Remove rooms

Team Operations

• create_team - Create teams
• list_teams - Browse teams
• get_team_details - Get team information
• update_team - Modify team settings
• delete_team - Remove teams

Membership Management

• create_membership - Add people to rooms
• list_memberships - View room members
• update_membership - Change member roles
• delete_membership - Remove members
• create_team_membership - Add team members
• list_team_memberships - View team members

People & Directory

• get_my_own_details - Get your profile
• list_people - Search for users
• get_person_details - Get user information
• create_person - Add new users (admin only)
• update_person - Modify user details
• delete_person - Remove users (admin only)

Webhooks & Events

• create_webhook - Set up event notifications
• list_webhooks - Manage webhooks
• get_webhook_details - Get webhook information
• update_webhook - Modify webhooks
• delete_webhook - Remove webhooks
• list_events - Get activity logs
• get_event_details - Get specific event information

Enterprise Features

• create_room_tab - Add tabs to rooms
• list_room_tabs - View room tabs
• get_room_tab_details - Get tab information
• update_room_tab - Modify tabs
• delete_room_tab - Remove tabs
• create_attachment_action - Handle form submissions
• get_attachment_action_details - Get attachment details
• list_ecm_folder - Enterprise content management
• get_ecm_folder_details - Get ECM folder details
• create_ecm_folder - Create ECM configurations
• update_ecm_linked_folder - Modify ECM folders
• unlink_ecm_linked_folder - Remove ECM links

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:

• Health Check: GET http://localhost:3001/health
• MCP Endpoint: POST http://localhost:3001/mcp
• Session Management: Automatic session ID handling
• CORS Support: Proper cross-origin configuration
• Protocol: MCP 2025-06-18 with StreamableHTTP transport

Environment Variables:

• MCP_MODE=http - Force HTTP mode
• PORT=3001 - Custom port (default: 3001)

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

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:

• Proper CORS configuration with mcp-session-id header exposure
• Session management for stateful connections
• Server-Sent Events (SSE) response format

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

🔧 Technical Details

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

• Non-root container: Runs as user mcp (UID 1001)
• Multi-stage build: Optimized production image
• Environment isolation: Secrets passed via environment variables
• Health checks: Container monitoring support

🧪 Testing

Comprehensive Test Suite

• 118 unit tests across 53 test suites
• 100% pass rate with comprehensive coverage
• 50+ API endpoints tested end-to-end
• 20+ critical bug fixes validated

# 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:

• JavaScript syntax checking
• All 118 unit tests must pass
• Code quality standards
• API implementation correctness

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

• Issues: Report bugs and feature requests via GitHub issues
• Documentation: See SETUP-COMPLETE.md for detailed setup instructions
• Community: Join discussions in the MCP community channels