Skip to main content
Version: 0.0.2

Environment Configuration

Both the MCP server and webhook server share common environment variable requirements for Slack integration, queue backends, and basic configuration. This guide covers all shared environment variables used across both server types.

Configuration Priority Order​

Environment Loading Priority

When running the Slack MCP Server, configuration values are loaded in the following priority order (highest to lowest):

  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, making it easier to manage different environments without worrying about accidental overrides from command-line options.

Example:

# In your .env file
SLACK_BOT_TOKEN=xoxb-production-token

# Even if you run with --slack-token argument, the .env value wins
slack-mcp-server --slack-token xoxb-dev-token  # Still uses xoxb-production-token from .env

# To use CLI argument instead, disable .env file loading
slack-mcp-server --slack-token xoxb-dev-token --no-env-file  # Now uses xoxb-dev-token

Required Environment Variables​

Slack Authentication​

The primary requirement for both servers is Slack bot authentication:

# Slack bot token (required for both MCP and webhook servers)
SLACK_BOT_TOKEN="xoxb-your-bot-token-here"

How to get your bot token:

  1. Go to Slack API Apps
  2. Create a new app or select an existing one
  3. Navigate to "OAuth & Permissions"
  4. Copy the "Bot User OAuth Token" (starts with xoxb-)

Optional Environment Variables​

Alternative Authentication Variables​

# Alternative token variable (fallback, used by some legacy configurations)
SLACK_TOKEN="xoxb-your-bot-token-here"

# Additional Slack credentials (for advanced features)
SLACK_BOT_ID="B1234567890"                    # Your bot's user ID
SLACK_USER_TOKEN="xoxp-your-user-token"       # For user-level operations
SLACK_SIGNING_SECRET="your-signing-secret"    # For webhook request verification

Development and Testing Variables​

# Test channel configuration (useful for development/testing)
SLACK_TEST_CHANNEL="#dev-testing"             # Channel name with #
SLACK_TEST_CHANNEL_ID="C1234567890"          # Channel ID (recommended)

Queue Backend Configuration​

Both servers support multiple queue backend options for handling asynchronous operations:

# Queue backend selection
QUEUE_BACKEND="memory"    # Options: memory | redis | kafka | custom_backend_name

# Redis backend settings (when QUEUE_BACKEND=redis)
REDIS_URL="redis://localhost:6379/0"

# Kafka backend settings (when QUEUE_BACKEND=kafka)  
KAFKA_BOOTSTRAP="broker1:9092,broker2:9092"

Queue Backend Options:

  • memory: In-memory queue (default, good for development)
  • redis: Redis-based queue (recommended for production)
  • kafka: Apache Kafka (for high-throughput scenarios)
  • custom plugins: Any custom queue backend plugin you develop
Develop Custom Queue Backend Plugins

You can extend the system with custom queue backends (e.g., RabbitMQ, AWS SQS, Google Pub/Sub) by implementing the QueueBackend protocol.

Use the Slack MCP Server Backend MQ Template to quickly create your own queue backend plugins with best practices and complete project structure.

📚 Documentation: https://chisanan232.github.io/Slack-MCP-Server-Backend-MQ-Template/

Environment File Loading Options​

Both the MCP server and webhook server support flexible environment file loading:

Default Behavior​

By default, the server automatically loads variables from .env in the current directory:

# Automatically loads from .env file
slack-mcp-server

# Automatically loads from .env file
slack-events-server

Custom Environment File​

Specify a custom environment file path:

# MCP server with custom env file
slack-mcp-server --env-file .env.production

# Webhook server with custom env file
slack-events-server --env-file /path/to/.env.staging

Disable Environment File Loading​

Disable automatic .env file loading (useful when relying only on system environment variables or CLI arguments):

# MCP server without .env file
slack-mcp-server --no-env-file --slack-token xoxb-your-token

# Webhook server without .env file
slack-events-server --no-env-file --slack-token xoxb-your-token

Environment File Examples​

Development Environment (.env.development)​

# Basic development configuration
SLACK_BOT_TOKEN="xoxb-your-development-token"
SLACK_TEST_CHANNEL="#dev-testing"
QUEUE_BACKEND="memory"

Production Environment (.env.production)​

# Basic production configuration
SLACK_BOT_TOKEN="xoxb-your-production-token"
QUEUE_BACKEND="redis"
REDIS_URL="redis://prod-redis:6379/0"

Testing Environment (.env.test)​

# Testing configuration
SLACK_BOT_TOKEN="xoxb-your-test-token"
SLACK_TEST_CHANNEL="#automated-testing"
SLACK_TEST_CHANNEL_ID="C9876543210"
QUEUE_BACKEND="memory"

Docker Environment Configuration​

When running servers in Docker containers, you can pass environment variables in several ways:

Using Environment Files​

# Run with environment file
docker run --env-file .env.production your-server-image

# Docker Compose
version: '3.8'
services:
  slack-server:
    image: your-server-image
    env_file:
      - .env.production

Using Environment Variables Directly​

# Pass individual environment variables
docker run \
  -e SLACK_BOT_TOKEN="xoxb-your-token" \
  -e QUEUE_BACKEND="redis" \
  -e REDIS_URL="redis://redis:6379/0" \
  your-server-image

Environment Variable Validation​

Both servers perform automatic validation of environment variables on startup:

Required Variable Validation​

  • Checks for presence of SLACK_BOT_TOKEN
  • Validates token format (must start with xoxb-)
  • Warns about missing optional variables

Queue Backend Validation​

  • Validates QUEUE_BACKEND value against allowed options
  • Checks backend-specific connection variables
  • Tests connectivity to external services (Redis/Kafka)

Common Validation Errors​

# Missing required token
❌ Error: SLACK_BOT_TOKEN environment variable is required

# Invalid token format
❌ Error: SLACK_BOT_TOKEN must start with 'xoxb-'

# Invalid queue backend
❌ Error: QUEUE_BACKEND must be one of: memory, redis, kafka

# Redis connection failed
❌ Error: Cannot connect to Redis at redis://localhost:6379/0

Security Best Practices​

Token Security​

  • Never commit tokens to version control
  • Use .env files and add them to .gitignore
  • Rotate tokens regularly in production
  • Use different tokens for different environments

Environment File Security​

  • Set appropriate file permissions: chmod 600 .env
  • Store production .env files securely
  • Use secrets management systems in production (e.g., Kubernetes secrets, AWS Secrets Manager)

Example .gitignore​

# Environment files
.env
.env.local
.env.development
.env.production
.env.test

# Backup env files
*.env.backup

Troubleshooting Environment Issues​

Token Issues​

# Test token validity
curl -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
     https://slack.com/api/auth.test

Redis Connection Issues​

# Test Redis connection
redis-cli -u $REDIS_URL ping

Environment Variable Debug​

# Check if variables are loaded
env | grep SLACK_
env | grep QUEUE_
env | grep REDIS_

For server-specific configuration options, see: