webex-bot-mcp 0.1.1

Model Context Protocol server for Webex Teams — manage rooms, messages, and memberships via AI assistants

Webex Bot MCP

A comprehensive Model Context Protocol (MCP) server that provides tools, resources, and prompts for interacting with Webex APIs using a Webex bot. This server enables automated messaging, room management, and team collaboration through the Webex platform.

Powered by: This MCP server is built on top of the excellent Webex Python SDK by the Webex Community. The SDK provides the robust foundation for all Webex API interactions in this project.

Features

🛠️ Tools (31 available)

• Room Management: Create, update, list, and manage Webex rooms/spaces
• Message Operations: Send messages with text, markdown, HTML, files, and mentions
• Membership Management: Add, remove, and update room memberships
• People Management: Search and manage organization users
• Dual Terminology: Full support for both "room" and "space" terminology

📚 Resources (10 available)

• Getting Started Guide: Dynamic setup and authentication status
• Message Formatting: Comprehensive formatting examples and best practices
• Current Configuration: Live bot status and capabilities
• Troubleshooting Guide: Common issues and solutions
• Security Best Practices: Production deployment security guidelines
• Use Cases & Examples: Real-world implementation patterns

🎯 Prompts (7 available)

• Send Announcement: Professional announcement templates
• Create Team Room: Guided room setup with member management
• Bulk Message Campaign: Multi-target messaging with rate limiting
• Room Management Workflow: Comprehensive room audit and maintenance
• Incident Response Setup: Emergency response coordination
• Bot Health Check: Comprehensive bot assessment
• Compliance Audit: Governance and policy compliance checking

🚀 Production Features

• Health Monitoring: Built-in health check endpoints
• Configuration Management: Environment-based configuration
• Container Support: Docker and Kubernetes deployment ready
• Security: Token management, rate limiting, audit logging
• Observability: Structured logging and metrics support

Prerequisites

Before setting up this MCP server, you'll need to create a Webex bot and obtain its access token.

Creating a Webex Bot

1. Go to the Webex Developer Portal:

   • Visit https://developer.webex.com
   • Sign in with your Webex account (create one if you don't have it)

2. Create a New Bot:

   • Click on "My Webex Apps" in the top navigation
   • Click "Create a New App"
   • Select "Create a Bot"

3. Configure Your Bot:

   • Bot Name: Choose a descriptive name (e.g., "Notification Bot", "Alert Bot")
   • Bot Username: This will be the bot's unique identifier (e.g., "notificationbot")
   • Icon: Upload an icon for your bot (optional but recommended)
   • Description: Describe what your bot does
   • Click "Add Bot"

4. Get Your Bot Access Token:

   • After creating the bot, you'll see the bot details page
   • Important: Copy the "Bot Access Token" immediately - this won't be shown again
   • The token starts with something like Y2lzY29zcGFyazovL3VzL0FQUExJQ0FUSU9O...
   • Store this token securely - you'll use it as your WEBEX_ACCESS_TOKEN

5. Bot Limitations to Know:

   • Bots can only see messages in rooms where they are explicitly added
   • To send messages to a room, the bot must be a member of that room
   • Bots cannot see messages in 1:1 spaces unless the other person messages the bot first
   • Bots have rate limits (typically 10 messages per second)

Adding Your Bot to Rooms

For your bot to send messages to rooms, it must be added as a member:

1. For Group Rooms:

   • Go to the Webex app
   • Open the room where you want the bot to send messages
   • Click the room name at the top
   • Click "People"
   • Click "Add People"
   • Search for your bot's username (e.g., "@notificationbot")
   • Add the bot to the room

2. For Direct Messages:

   • Users can start a 1:1 conversation with your bot by searching for its username
   • Or you can send direct messages using the user's email address

Installation

From PyPI (recommended)

pip install webex-bot-mcp

Or with uv:

uv tool install webex-bot-mcp

Once installed, the webex-bot-mcp command is available system-wide.

From source

Clone the repository and install with uv:

git clone https://github.com/WebexCommunity/webex-bot-mcp.git
cd webex-bot-mcp
uv sync

Installing uv

This project uses uv for Python package management. You'll need to install uv first.

Install uv

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative installation methods:

• Homebrew (macOS): brew install uv
• pip: pip install uv
• pipx: pipx install uv

Find uv Path for Claude Desktop

For Claude Desktop configuration, you may need the full path to uv. You can find it using:

which uv

This will return something like:

• macOS/Linux: /Users/username/.cargo/bin/uv or /usr/local/bin/uv
• Windows: C:\Users\username\.cargo\bin\uv.exe

If which uv doesn't work, try:

whereis uv

Note: If you installed uv via the official installer, it's typically located at:

• macOS/Linux: ~/.cargo/bin/uv
• Windows: %USERPROFILE%\.cargo\bin\uv.exe

You can use either the full path or just uv in your Claude Desktop configuration if uv is in your system PATH.

Setup

1. Install dependencies:

   uv sync
   

2. Configure environment variables:

   cp .env.example .env
   

   Edit .env and add your Webex bot access token:

   WEBEX_ACCESS_TOKEN=your_bot_access_token_here
   

3. Test Your Bot Token: You can verify your bot token works by testing it:

   curl -H "Authorization: Bearer YOUR_BOT_TOKEN" \
        https://webexapis.com/v1/people/me
   

   This should return your bot's information.

Common Use Cases for Bot Notifications

This MCP server is particularly useful for:

System Monitoring & Alerts

• Send server status updates to operations teams
• Alert on system failures or performance issues
• Notify about backup completion or failures
• Monitor application health and send alerts

CI/CD Pipeline Notifications

• Notify teams about build successes/failures
• Alert on deployment completions
• Send code review reminders
• Report test results

Business Process Notifications

• Customer support ticket alerts
• Sales pipeline updates
• Meeting reminders and follow-ups
• Report generation completion

Integration Examples

• Connect to monitoring tools (Prometheus, Grafana)
• Integrate with ticketing systems (Jira, ServiceNow)
• Hook into CI/CD platforms (Jenkins, GitHub Actions)
• Connect to business applications (Salesforce, HubSpot)

Best Practices

• Use markdown formatting for better message readability
• Include relevant context and action items in notifications
• Use threaded replies to keep conversations organized
• Set up different bots for different types of notifications
• Test your bot in a dedicated testing room first

Running the MCP Server

The server supports two transport types: stdio (default) and streamable-http.

Stdio Transport (Default)

webex-bot-mcp

Streamable HTTP Transport

webex-bot-mcp --transport streamable-http

You can also customize the host and port for HTTP transport:

webex-bot-mcp --transport streamable-http --host 0.0.0.0 --port 9000

Command Line Options

• --transport: Choose transport type (stdio or streamable-http, default: stdio)
• --host: Host to bind to for streamable-http transport (default: localhost)
• --port: Port to bind to for streamable-http transport (default: 8000)

Use --help to see all available options:

webex-bot-mcp --help

A standalone health check command is also available:

webex-bot-mcp-health
webex-bot-mcp-health --output text
webex-bot-mcp-health --skip-api  # environment check only

Claude Desktop Integration

To use this MCP server with Claude Desktop, you'll need to add the server configuration to your Claude Desktop config file.

Configuration File Location

The Claude Desktop configuration file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Standard Configuration (Stdio Transport)

If installed from PyPI (recommended), add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "webex-bot-mcp": {
      "command": "webex-bot-mcp",
      "env": {
        "WEBEX_ACCESS_TOKEN": "your_webex_bot_access_token_here"
      }
    }
  }
}

If running from a source checkout, use uv to run the CLI:

{
  "mcpServers": {
    "webex-bot-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/webex-bot-mcp",
        "run",
        "webex-bot-mcp"
      ],
      "env": {
        "WEBEX_ACCESS_TOKEN": "your_webex_bot_access_token_here"
      }
    }
  }
}

Note: If uv or webex-bot-mcp are not in your system PATH, use the full path to the binary. See the Installing uv section above for how to find the full path.

Setup Steps

1. Replace the placeholder: Change your_webex_bot_access_token_here to your actual Webex bot access token
2. Update the path (source checkout only): Change /path/to/your/webex-bot-mcp to match your actual project directory
3. Copy the configuration: Add the configuration to your Claude Desktop config file
4. Restart Claude Desktop: Close and reopen Claude Desktop to load the new configuration
5. Test the MCP server: You can now use the MCP server in Claude Desktop to interact with Webex rooms and send messages

Sample Prompts for AI Agents

This MCP server enables AI agents to interact with Webex messaging through natural language prompts. Here are practical examples of how agents can utilize the Webex bot:

Incident Management & Operations

"Create an incident room and notify the on-call team"

Create a new Webex room called "INCIDENT-2025-001-Database-Outage" and send a message to it with:
- Incident severity: P1
- Affected service: Customer Database
- Initial symptoms: Connection timeouts
- Next steps: Investigating root cause
Then send direct messages to the on-call engineers:
- [e-mail]
- [e-mail]
- [e-mail]
Alert them about the new incident room and ask them to join immediately.

"Send maintenance notifications to multiple teams"

Send a maintenance notification to the following Webex rooms:
- "Engineering Team"
- "Customer Support" 
- "Operations"
- "QA Team"

Message should include:
- Maintenance window: Tonight 11 PM - 2 AM EST
- Affected services: Payment processing, user authentication
- Expected downtime: 15 minutes
- Contact person: DevOps team for questions

Automated Monitoring & Alerts

"Send system health updates to operations rooms"

Check our monitoring dashboard and send a daily health summary to the "Operations" room including:
- Server uptime status
- Database performance metrics
- API response times
- Any alerts or warnings from the last 24 hours
Format it nicely with markdown for easy reading.

"Alert about CI/CD pipeline failures"

The build pipeline for project "customer-portal" just failed on the main branch.
Send an alert to the "Engineering Team" room with:
- Build ID: #2045
- Failed stage: Integration Tests
- Error summary: Database connection timeout
- Assigned to: @backend-team
- Link to build logs: [provide the link]

Customer Support & Communication

"Escalate support tickets to engineering"

We have a P1 customer issue that needs engineering attention.
Create a room called "CUSTOMER-ISSUE-Netflix-Streaming" and invite:
- [e-mail]
- [e-mail]
- [e-mail]

Send the initial context:
- Customer: Netflix
- Issue: Streaming service integration failing
- Impact: 50,000+ users affected
- Ticket ID: SUP-12345
- Customer contact: [e-mail]

"Send release notes to stakeholders"

We just deployed version 3.2.1 to production. Send release notes to:
- "Product Team" room
- "Customer Success" room
- "Executive Updates" room

Include:
- New features: Advanced analytics dashboard, mobile push notifications
- Bug fixes: 12 critical issues resolved
- Performance improvements: 30% faster page load times
- Breaking changes: None
- Rollback plan: Available if needed

Team Coordination & Project Management

"Coordinate cross-team project updates"

Send a weekly project status update to the "Project Alpha" room and individual updates to:
- [e-mail]
- [e-mail]
- [e-mail]

Status should include:
- Completed this week: User authentication module
- In progress: Payment integration
- Blocked: Waiting for security review
- Next week's goals: Complete checkout flow
- Risks: Potential delay in third-party API integration

"Schedule and announce team meetings"

Send meeting invitations to the "Architecture Review" room for next Tuesday at 2 PM EST.
Agenda:
- Review microservices communication patterns
- Discuss database sharding strategy
- Plan for Q3 scalability improvements
- Action items from last meeting

Also send individual reminders to:
- [e-mail]
- [e-mail]
- [e-mail]

Compliance & Security Alerts

"Send security incident notifications"

We detected a potential security incident. Send immediate alerts to:
- "Security Team" room
- "IT Leadership" room
- Direct messages to CISO and IT Director

Include:
- Incident type: Unusual login patterns detected
- Affected systems: Customer portal
- Action taken: Accounts temporarily locked
- Investigation status: In progress
- Next steps: Full security audit initiated

"Compliance audit reminders"

Send SOC 2 audit preparation reminders to compliance stakeholders:
- "Compliance Team" room
- "Engineering Leadership" room
- Individual messages to department heads

Reminder should include:
- Audit date: Next Friday
- Required documentation: Security policies, access logs, change management records
- Point of contact: [e-mail]
- Preparation checklist: [attach file]

Integration & Automation Examples

"Multi-channel deployment notifications"

After a successful production deployment, automatically send notifications to:
1. "Engineering Team" room - Technical details and metrics
2. "Product Team" room - Feature summary and user impact
3. "Customer Support" room - What to expect and how to help customers
4. Direct message to release manager with detailed deployment log

"Escalation workflows"

If a P1 incident isn't acknowledged within 15 minutes:
1. Send escalation alert to "Critical Incidents" room
2. Page the on-call manager directly
3. Create a conference bridge and share details
4. Notify executive team if incident exceeds 1 hour
5. Update incident status in all relevant rooms

These examples demonstrate how AI agents can use natural language to orchestrate complex Webex messaging workflows, making incident response, team coordination, and operational communications more efficient and automated.