Webex MCP Server

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

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

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

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:

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

Installation

Clone and install dependencies:

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

Configure environment:

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

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

Docker Usage

Build and run:

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

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

Visit developer.webex.com
Sign in with your Cisco/Webex account
Copy the bearer token from the API documentation
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": "[email protected]",
        "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

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

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

Create a new tool file in tools/webex-public-workspace/webex-messaging/
Follow the existing tool pattern with proper imports
Add the tool path to tools/paths.js
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

Fork the repository
Create a feature branch
Make your changes
Tests run automatically on commit via pre-commit hooks
Ensure all 118 tests pass
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

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github		.github
.husky		.husky
commands		commands
lib		lib
scripts		scripts
tests		tests
tools		tools
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
discover-tools.js		discover-tools.js
docker-compose.yml		docker-compose.yml
index.js		index.js
mcpServer.js		mcpServer.js
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
tools-manifest.json		tools-manifest.json

License

Kashyap-AI-ML-Solutions/webex-messaging-mcp-server

Folders and files

Latest commit

History

Repository files navigation

Webex MCP Server

Overview

Features

Quick Start

Prerequisites

Token Renewal

Installation

🔍 Tool Discovery

Tool Discovery Commands

Tool Manifest

Tool Organization

Docker Usage

Configuration

Environment Variables

Getting a Webex API Token

MCP Client Integration

Claude Desktop (STDIO Mode)

HTTP Mode Integration

Other MCP Clients

Available Tools

Core Messaging

Room Management

Team Operations

Membership Management

People & Directory

Webhooks & Events

Enterprise Features

Transport Modes

STDIO Mode (Default)

HTTP Mode (StreamableHTTP)

Smithery Integration

Development

Project Structure

Adding New Tools

Security

Testing

🧪 Comprehensive Test Suite

🔒 Pre-Commit Quality Gates

Contributing

License

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Packages