Skip to main content
Version: Next

Webhook Server CLI Reference

The Slack Webhook Server provides a comprehensive command-line interface for starting and configuring both standalone and integrated server modes. This reference covers all available CLI options, usage patterns, and examples.

Basic Usage​

The webhook server can be started using multiple execution methods:

# After installation via pip/uv/poetry
slack-webhook-server [OPTIONS]

Command Options​

Server Mode Options​

--integrated​

Type: Flag
Default: False
Description: Enable integrated mode (webhook + MCP server combined).

# Standalone webhook server (default)
python -m slack_mcp.webhook

# Explicitly specify standalone mode
python -m slack_mcp.webhook --no-integrated

MCP Integration Options (Integrated Mode Only)​

--mcp-transport​

Type: Choice
Choices: sse, streamable-http
Default: sse
Description: MCP transport protocol (integrated mode only).

# Server-Sent Events (default for integrated mode)
python -m slack_mcp.webhook --integrated --mcp-transport sse

# Custom mount path for SSE
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --mcp-mount-path /api/mcp

--mcp-mount-path​

Type: String
Default: /mcp
Description: Mount path for MCP SSE endpoints (SSE transport only).

# Default mount path
python -m slack_mcp.webhook --integrated --mcp-mount-path /mcp

# Custom mount path
python -m slack_mcp.webhook --integrated --mcp-mount-path /api/v1/mcp

# Root mount path
python -m slack_mcp.webhook --integrated --mcp-mount-path /

Network Options​

--host​

Type: String
Default: 0.0.0.0
Description: Host interface to bind the server.

# Local development (localhost only)
python -m slack_mcp.webhook --host 127.0.0.1

# Specific IP address
python -m slack_mcp.webhook --host 192.168.1.100

--port​

Type: Integer
Default: 3000
Range: 1-65535
Description: Port number for the webhook server.

# Default port
python -m slack_mcp.webhook --port 3000

# Custom port
python -m slack_mcp.webhook --port 8080

# Auto-assign available port
python -m slack_mcp.webhook --port 0

Authentication & Environment Options​

Configuration Priority Order

When running the webhook server, configuration values are loaded in this priority order:

  1. .env file (HIGHEST PRIORITY) - Values in your .env file override everything
  2. CLI arguments (--slack-token) - Used as fallback if not set in .env file
  3. Environment variables - Already set environment variables (lowest priority)

This means your .env file values will always take precedence over CLI arguments.

--slack-token​

Type: String
Default: None
Description: Slack bot token (fallback if not set in .env file or SLACK_BOT_TOKEN environment variable).

# CLI argument is used as fallback (if not in .env file)
python -m slack_mcp.webhook --slack-token "xoxb-your-token-here"

# Disable .env file loading to force CLI argument usage
python -m slack_mcp.webhook --slack-token "xoxb-your-token-here" --no-env-file

# Use .env file (recommended - highest priority)
# Create .env file with: SLACK_BOT_TOKEN=xoxb-your-token
python -m slack_mcp.webhook

--env-file​

Type: String
Default: .env
Description: Path to environment file.

# Use default .env file
python -m slack_mcp.webhook

# Explicitly specify .env file
python -m slack_mcp.webhook --env-file .env

--no-env-file​

Type: Flag
Default: False
Description: Disable automatic environment file loading.

# Disable .env file loading (use only system environment variables)
python -m slack_mcp.webhook --no-env-file

# Cloud deployment without .env files
python -m slack_mcp.webhook --no-env-file --host 0.0.0.0 --port ${PORT}

Logging & Debugging Options​

--log-level​

Type: String
Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL (case-insensitive)
Default: INFO
Description: Sets the logging verbosity level. Accepts both uppercase and lowercase values (e.g., debug, DEBUG, Debug all work).

# Case-insensitive - all these work the same way
python -m slack_mcp.webhook --log-level debug
python -m slack_mcp.webhook --log-level DEBUG

# Development with integrated mode
python -m slack_mcp.webhook --integrated --log-level debug

Log Level Details:

  • DEBUG: Detailed diagnostic information. Use for development and troubleshooting.
  • INFO: General informational messages. Good for production monitoring.
  • WARNING: Warning messages for potentially problematic situations.
  • ERROR: Error messages for serious problems.
  • CRITICAL: Critical error messages for fatal problems.
Case-Insensitive Input

The --log-level option accepts any case variation (debug, DEBUG, Debug, etc.), making it more user-friendly and compatible with different scripting conventions.

--log-file​

Type: String
Default: None (console only)
Description: Path to log file. When specified, logs are written to both console and file with automatic rotation.

slack-webhook-server --log-file /var/log/slack-webhook.log

--log-dir​

Type: String
Default: logs
Description: Directory for log files when --log-file is a relative path.

slack-webhook-server --log-dir /var/log/slack-webhook

--log-format​

Type: String
Default: %(asctime)s [%(levelname)8s] %(name)s: %(message)s
Description: Custom log message format using Python logging format syntax.

slack-webhook-server --log-format "%(asctime)s %(levelname)s: %(message)s"
Logging Configuration

For detailed logging configuration including file rotation, environment variables, and programmatic usage, see the Logging Configuration Guide.

--retry​

Type: Integer
Default: 3
Range: 0-10
Description: Maximum number of retry attempts for failed requests.

# Default retry attempts
python -m slack_mcp.webhook --retry 3

# No retries (fail fast)
python -m slack_mcp.webhook --retry 0

# High retry for unstable networks
python -m slack_mcp.webhook --retry 5

Usage Examples​

Standalone Mode Examples​

# Simple standalone webhook server
python -m slack_mcp.webhook

# Explicit configuration
python -m slack_mcp.webhook \
  --host 0.0.0.0 \
  --port 3000 \
  --log-level info

Integrated Mode Examples​

# Simple integrated server (webhook + MCP)
python -m slack_mcp.webhook --integrated

# Explicit SSE transport
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --mcp-mount-path /mcp

Container Deployment Examples​

# Docker container configuration
python -m slack_mcp.webhook \
  --host 0.0.0.0 \
  --port 3000 \
  --log-level info \
  --no-env-file

# Integrated mode in container
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --host 0.0.0.0 \
  --port 3000 \
  --no-env-file

Environment Variable Override​

CLI options can be overridden by environment variables:

CLI OptionEnvironment VariableExample
--hostHOSTexport HOST=0.0.0.0
--portPORTexport PORT=8080
--log-levelLOG_LEVELexport LOG_LEVEL=DEBUG
--mcp-transportMCP_TRANSPORTexport MCP_TRANSPORT=sse
--mcp-mount-pathMCP_MOUNT_PATHexport MCP_MOUNT_PATH=/api
--retryRETRY_ATTEMPTSexport RETRY_ATTEMPTS=5

Precedence: CLI arguments override environment variables, which override defaults.

# Environment variable with CLI override
export PORT=8080
export LOG_LEVEL=WARNING

# This will use port 3000 and DEBUG level (CLI overrides)
python -m slack_mcp.webhook --port 3000 --log-level DEBUG

Configuration Scripts​

Startup Script Examples​

Development Script (start-webhook-dev.sh)​

#!/bin/bash
# start-webhook-dev.sh

export SLACK_BOT_TOKEN="xoxb-your-dev-token"
export SLACK_SIGNING_SECRET="your-dev-signing-secret"

echo "Starting webhook server in development mode..."
python -m slack_mcp.webhook \
  --host 127.0.0.1 \
  --port 3000 \
  --log-level debug \
  --env-file .env.development

Production Script (start-webhook-prod.sh)​

#!/bin/bash
# start-webhook-prod.sh

# Load environment variables
source .env.production

echo "Starting webhook server in production mode..."
python -m slack_mcp.webhook \
  --host ${HOST:-0.0.0.0} \
  --port ${PORT:-8080} \
  --log-level ${LOG_LEVEL:-INFO} \
  --retry ${RETRY_ATTEMPTS:-5}

Integrated Mode Script (start-integrated.sh)​

#!/bin/bash
# start-integrated.sh

source .env.production

echo "Starting integrated server (webhook + MCP)..."
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport ${MCP_TRANSPORT:-sse} \
  --mcp-mount-path ${MCP_MOUNT_PATH:-/mcp} \
  --host ${HOST:-0.0.0.0} \
  --port ${PORT:-8080} \
  --log-level ${LOG_LEVEL:-INFO}

Process Management​

Using systemd​

Create a systemd service (/etc/systemd/system/webhook-server.service):

[Unit]
Description=Slack Webhook Server
After=network.target

[Service]
Type=simple
User=webhook
WorkingDirectory=/opt/slack-webhook-server
EnvironmentFile=/opt/slack-webhook-server/.env.production
ExecStart=/opt/slack-webhook-server/venv/bin/python -m slack_mcp.webhook \
  --host 0.0.0.0 \
  --port 8080 \
  --log-level INFO
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Help and Version Information​

Display Help​

# Show all available options
slack-webhook-server --help

# Show version information
slack-webhook-server --version

Troubleshooting CLI Issues​

Common Problems​

1. Port Already in Use​

# Error: Address already in use
python -m slack_mcp.webhook --port 3000

# Solution: Find and kill process or use different port
lsof -ti:3000 | xargs kill -9
# OR
python -m slack_mcp.webhook --port 3001

2. Permission Denied​

# Error: Permission denied on port 80
python -m slack_mcp.webhook --port 80

# Solution: Use non-privileged port
python -m slack_mcp.webhook --port 8080

3. Missing Environment Variables​

# Error: Missing SLACK_BOT_TOKEN
python -m slack_mcp.webhook

# Solution: Set required environment variables
export SLACK_BOT_TOKEN="xoxb-your-token"
export SLACK_SIGNING_SECRET="your-secret"
python -m slack_mcp.webhook

Debug Mode​

Enable maximum verbosity for troubleshooting:

# Maximum debug output
python -m slack_mcp.webhook \
  --log-level debug \
  --retry 0

# Debug integrated mode
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --log-level debug

For comprehensive webhook server setup: