npm package: @iflow-mcp/webex-messaging-mcp-server
Description: A comprehensive MCP server providing AI assistants with full access to Cisco Webex messaging capabilities including messages, rooms, teams, people, webhooks, and enterprise features.
Author: Kashyap Kambhatla
Latest version: 0.1.0

[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/kashyap-ai-ml-solutions-webex-messaging-mcp-server-badge.png)](https://mseep.ai/app/kashyap-ai-ml-solutions-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.

<a href="https://glama.ai/mcp/servers/@Kashyap-AI-ML-Solutions/webex-messaging-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Kashyap-AI-ML-Solutions/webex-messaging-mcp-server/badge" alt="Webex Server MCP server" />
</a>

## 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](https://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:**
   ```bash
   git clone <repository-url>
   cd webex-messaging-mcp-server
   npm install
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your Webex API token
   ```

3. **Test the server:**
   ```bash
   # 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

```bash
# 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

1. **Build and run:**
   ```bash
   docker build -t webex-mcp-server .
   docker run -i --rm --env-file .env webex-mcp-server
   ```

2. **Using docker-compose:**
   ```bash
   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](https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms)
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:

```json
{
  "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:

```bash
# 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:
```bash
docker run -i --rm --env-file .env webex-mcp-server
```

For HTTP mode:
```bash
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:

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

### HTTP Mode (StreamableHTTP)
HTTP-based transport supporting MCP 2025-06-18 protocol:

```bash
# 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](https://smithery.ai) with HTTP runtime:

```yaml
# 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

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

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

```bash
# 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