Skip to main content

Webex Bot - AI Assistant

Bring any LLM and your MCP tools into Webex spaces, with thread-aware conversations

PyPI Python License

Pre-commit Checks Docker published

Quick start · Configuration · MCP integration · Usage

A conversational AI bot for Webex that:

  • 🤖 Responds to user mentions with AI-generated answers
  • 💬 Maintains conversation context within threads
  • 🔧 Integrates with MCP (Model Context Protocol) servers for extended capabilities
  • 🌐 Supports multiple LLM providers via LiteLLM (OpenAI, Google Gemini, Ollama, OpenRouter, Anthropic, etc.)

✨ Features

  • Thread-aware conversations: The bot remembers context within Webex threads, allowing natural follow-up questions
  • Rolling thread summarization: Background tasks summarize older messages as threads grow, preserving context indefinitely without hitting context limits
  • Room-wide history search: Uses SQLite FTS5 keyword search to look up past messages, solutions, and context across Webex space history
  • Smart mention handling: The bot recognizes its own name and doesn't confuse it with questions
  • Multiple LLM providers: Use OpenAI, Google Gemini, Ollama (local/cloud), OpenRouter, Anthropic, or any LiteLLM-supported provider
  • MCP Integration: Connect to multiple MCP servers via HTTP for extended tool capabilities
  • Access control: Restrict bot to approved users, domains, or rooms
  • Clean code: Follows Python best practices with ruff linting and formatting

🚀 Quick Start

Prerequisites

  • Python 3.11 to 3.14
  • UV package manager
  • Webex bot token (create one here)
  • API key for your LLM provider (e.g., OpenAI, Gemini)

Installation

Option 1: Install from PyPI

Run the package directly from PyPI using UVX:

uvx webex-bot-ai

Option 2: Local Development Setup

For development or running from source:

  1. Install dependencies:
git clone https://github.com/mhajder/webex-bot-ai.git
cd webex-bot-ai
uv sync

Option 3: Run with Docker (Persistent Storage)

Run in a container with database volume persistence:

docker run -d \
  --name webex-bot-ai \
  --env-file .env \
  -v webex_bot_data:/app/data \
  ghcr.io/mhajder/webex-bot-ai:latest

Configuration

  1. Configure environment:
cp .env.example .env
# Edit .env with your configuration
  1. Set required variables in .env:
WEBEX_ACCESS_TOKEN=your_webex_bot_token
OPENAI_API_KEY=your_openai_api_key
  1. Run the bot:
webex-bot-ai

🔧 Configuration

Bot Settings

Variable Description Default
WEBEX_ACCESS_TOKEN Webex bot access token (required) -
BOT_NAME Bot name for mention handling Assistant
BOT_DISPLAY_NAME Display name in Webex AI Assistant

LLM Settings

Variable Description Default
LLM_MODEL LiteLLM model identifier gpt-4o-mini
LLM_TEMPERATURE Sampling temperature (0.0-2.0) 0.7
LLM_MAX_TOKENS Maximum response tokens 2048
LLM_API_BASE Custom API endpoint -
LLM_API_KEY API key passed to LiteLLM; when unset, the provider's own variable (e.g. OPENAI_API_KEY) is used -

Conversation Settings & Rolling Summarization

Variable Description Default
CONVERSATION_ENABLE_PERSISTENCE Persist conversation threads to SQLite database true
CONVERSATION_ENABLE_SUMMARIZATION Enable rolling thread summarization for long threads true
CONVERSATION_SUMMARY_THRESHOLD Message count threshold to trigger rolling summarization 50
CONVERSATION_KEEP_RECENT_MESSAGES Number of recent messages retained verbatim after summary 20
CONVERSATION_SUMMARY_MODEL Optional distinct LLM model for thread summarization Same as LLM_MODEL
CONVERSATION_SUMMARY_API_KEY API key for the summary model LLM_API_KEY if same provider as LLM_MODEL, else the provider's own env var
CONVERSATION_SUMMARY_API_BASE API base URL for the summary model LLM_API_BASE if same provider as LLM_MODEL
CONVERSATION_MAX_HISTORY_MESSAGES Maximum in-memory history messages 50
CONVERSATION_TIMEOUT_HOURS Hours before a thread is considered stale 24
CONVERSATION_RETENTION_DAYS Days to keep inactive threads in the database (0 = forever); cleanup runs at startup and daily 30
CONVERSATION_DB_PATH SQLite database file path conversations.db

Model Examples

# OpenAI
LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-...

# Google Gemini
LLM_MODEL=gemini/gemini-2.5-flash
GEMINI_API_KEY=AIzaSy...

# Ollama (local)
LLM_MODEL=ollama_chat/gpt-oss:120b
LLM_API_BASE=http://localhost:11434

# OpenRouter
LLM_MODEL=openrouter/meta-llama/llama-3.1-70b-instruct
OPENROUTER_API_KEY=sk-or-...

# Anthropic
LLM_MODEL=claude-3-sonnet-20240229
ANTHROPIC_API_KEY=sk-ant-...

Access Control

# Restrict to specific users
WEBEX_APPROVED_USERS=user1@example.com,user2@example.com

# Restrict to specific email domains
WEBEX_APPROVED_DOMAINS=example.com

# Restrict to specific rooms
WEBEX_APPROVED_ROOMS=room_id_1,room_id_2

MCP Integration

Connect to MCP HTTP transport servers for extended tool capabilities:

MCP_ENABLED=true
MCP_REQUEST_TIMEOUT=30

# Single server
MCP_SERVERS=[{"name": "my-server", "url": "http://localhost:8000/mcp", "enabled": true}]

# Multiple servers with auth
MCP_SERVERS='[
  {"name": "tools-server", "url": "http://localhost:8000/mcp", "enabled": true},
  {"name": "secure-server", "url": "https://api.example.com/mcp", "auth_token": "your-token", "enabled": true}
]'

Sentry Error Tracking (Optional)

Enable error tracking and performance monitoring with Sentry:

# Install with Sentry support
uv sync --extra sentry

Configure Sentry via environment variables:

Variable Description Default
SENTRY_DSN Sentry DSN (enables Sentry when set) -
SENTRY_TRACES_SAMPLE_RATE Trace sampling rate (0.0-1.0) 0.1
SENTRY_SEND_DEFAULT_PII Include PII in events: user emails/names, LLM prompts and responses, INFO log breadcrumbs false
SENTRY_ENVIRONMENT Environment name (e.g., production) -
SENTRY_RELEASE Release/version identifier Package version
SENTRY_PROFILE_SESSION_SAMPLE_RATE Profile session sampling rate 0.1
SENTRY_PROFILE_LIFECYCLE Profile lifecycle mode trace
SENTRY_ENABLE_LOGS Enable logging integration true

Example configuration:

# Enable Sentry error tracking
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
SENTRY_ENVIRONMENT=production

💡 Usage

  1. Start a conversation: Mention the bot in a Webex space:

    @BotName What is AI?
    
  2. Follow-up in thread: Reply in the same thread for context-aware responses:

    @BotName Tell me more.
    
  3. The bot maintains context within the thread, so you can have natural conversations.

🔨 Development

uv sync --group dev
uv run prek install

# Lint, format and type-check
uv run ruff check .
uv run ruff format .
uv run ty check .

Adding New Features

  • Commands: Add new commands in src/commands/
  • MCP Tools: Connect to MCP servers via configuration
  • LLM Providers: Configure via LLM_MODEL using LiteLLM syntax

📦 Dependencies

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, checks and commit message format, and use the issue templates for bugs and feature requests.

Found a security problem? Please report it privately as described in SECURITY.md.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for webex-bot-ai 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for webex-bot-ai 0.3.1
File Size Uploaded Provenance Actions
webex_bot_ai-0.3.1.tar.gz 239.5 kB With provenance Details for webex_bot_ai-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for webex-bot-ai 0.3.1
File Interpreter ABI Platform Actions
webex_bot_ai-0.3.1-py3-none-any.whl Python 3 none any Details for webex_bot_ai-0.3.1-py3-none-any.whl

Total release size: 290.4 kB

Release files / webex_bot_ai-0.3.1.tar.gz

Download URL webex_bot_ai-0.3.1.tar.gz
Size 239.5 kB
Tags Source
SHA-256 checksum
How to use checksums
75cf4a5dc144d5d0c6655abe5c58ce2737411ce13e1968d734b79c319e51c825
BLAKE2b-256 checksum
How to use checksums
e085f9f8beaee4c727a6e7cc11ffeea3f0b226b6b99e77a5701c44ca61b6cb1a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / webex_bot_ai-0.3.1-py3-none-any.whl

Download URL webex_bot_ai-0.3.1-py3-none-any.whl
Size 51.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e75fc68501c9d8eee38e282f10220b3501467aeb48e7884b6b95c9e5f53090f9
BLAKE2b-256 checksum
How to use checksums
6c8411a37d34357d9d0d3819d09951e7b1acc5e4d9784050eaf63c438b65ecfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for webex-bot-ai 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for webex_bot_ai-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page