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.
- 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
- 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
- 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
- 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
Before setting up this MCP server, you'll need to create a Webex bot and obtain its access token.
-
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)
-
Create a New Bot:
- Click on "My Webex Apps" in the top navigation
- Click "Create a New App"
- Select "Create a Bot"
-
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"
-
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
-
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)
For your bot to send messages to rooms, it must be added as a member:
-
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
-
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
This project uses uv for Python package management. You'll need to install uv first.
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows:
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
For Claude Desktop configuration, you may need the full path to uv. You can find it using:
which uvThis will return something like:
- macOS/Linux:
/Users/username/.cargo/bin/uvor/usr/local/bin/uv - Windows:
C:\Users\username\.cargo\bin\uv.exe
If which uv doesn't work, try:
whereis uvNote: 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.
-
Install dependencies:
uv sync
-
Configure environment variables:
cp .env.example .env
Edit
.envand add your Webex bot access token:WEBEX_ACCESS_TOKEN=your_bot_access_token_here -
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/meThis should return your bot's information.
This MCP server is particularly useful for:
- 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
- Notify teams about build successes/failures
- Alert on deployment completions
- Send code review reminders
- Report test results
- Customer support ticket alerts
- Sales pipeline updates
- Meeting reminders and follow-ups
- Report generation completion
- 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)
- 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
The server supports two transport types: stdio (default) and streamable-http.
uv run main.pyuv run main.py --transport streamable-httpYou can also customize the host and port for HTTP transport:
uv run main.py --transport streamable-http --host 0.0.0.0 --port 9000--transport: Choose transport type (stdioorstreamable-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:
uv run main.py --helpTo use this MCP server with Claude Desktop, you'll need to add the server configuration to your Claude Desktop config file.
The Claude Desktop configuration file is located at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add this configuration to your claude_desktop_config.json:
{
"mcpServers": {
"webex-bot-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/webex-bot-mcp",
"run",
"main.py"
],
"env": {
"WEBEX_ACCESS_TOKEN": "your_webex_bot_access_token_here"
}
}
}
}Note: If uv is not in your system PATH, replace "uv" with the full path to uv (e.g., "/Users/username/.cargo/bin/uv" on macOS/Linux or "C:\\Users\\username\\.cargo\\bin\\uv.exe" on Windows). See the Installing uv section above for how to find the full path.
- Replace the placeholder: Change
your_webex_bot_access_token_hereto your actual Webex bot access token - Update the path: Change
/path/to/your/webex-bot-mcpto match your actual project directory location - Copy the configuration: Add the configuration to your Claude Desktop config file
- Restart Claude Desktop: Close and reopen Claude Desktop to load the new configuration
- Test the MCP server: You can now use the MCP server in Claude Desktop to interact with Webex rooms and send messages
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:
"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:
- john.doe@company.com
- jane.smith@company.com
- ops-lead@company.com
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
"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]
"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:
- support-manager@company.com
- engineering-lead@company.com
- customer-success@company.com
Send the initial context:
- Customer: Netflix
- Issue: Streaming service integration failing
- Impact: 50,000+ users affected
- Ticket ID: SUP-12345
- Customer contact: tech-contact@netflix.com
"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
"Coordinate cross-team project updates"
Send a weekly project status update to the "Project Alpha" room and individual updates to:
- engineering-manager@company.com
- product-owner@company.com
- design-lead@company.com
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:
- senior-architect@company.com
- database-admin@company.com
- platform-engineer@company.com
"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: compliance-officer@company.com
- Preparation checklist: [attach file]
"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.