Skip to main content
Version: Next

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 from the abstract-backend library
Queue Backend Plugins

Queue backend implementations are provided by the abstract-backend library. For information about available backends and developing custom queue backend plugins, refer to the abstract-backend documentation.

Web Server CORS Configuration​

The webhook server includes configurable CORS (Cross-Origin Resource Sharing) settings to control which origins can access the server:

# Allowed origins for CORS requests
CORS_ALLOW_ORIGINS="*"  # Default: allow all origins

# Allow credentials in CORS requests (cookies, authorization headers, etc.)
CORS_ALLOW_CREDENTIALS="true"  # Default: true

# Allowed HTTP methods for CORS requests
CORS_ALLOW_METHODS="*"  # Default: allow all methods

# Allowed HTTP headers for CORS requests
CORS_ALLOW_HEADERS="*"  # Default: allow all headers

CORS Configuration Examples:

# Development: Allow local origins
CORS_ALLOW_ORIGINS="http://localhost:3000,http://localhost:8080"
CORS_ALLOW_CREDENTIALS="true"
CORS_ALLOW_METHODS="GET,POST,PUT,DELETE,OPTIONS"
CORS_ALLOW_HEADERS="Content-Type,Authorization,X-Requested-With"

CORS Security Considerations:

  • Development: Use "*" or local origins for easier testing
  • Production: Always specify exact domains for better security
  • Credentials: Only enable CORS_ALLOW_CREDENTIALS="true" when needed
  • Methods: Limit to only the HTTP methods your application actually uses
  • Headers: Restrict to only the headers your application requires

Environment File Structure​

The Slack MCP Server uses separate environment files for different purposes to maintain clear separation between production and testing configurations:

📁 Production Environment Configuration​

File: .env.example → .env (root directory)

  • Purpose: Production server configuration
  • Usage: MCP server, webhook server, and integrated server
  • Contains: All production environment variables with detailed documentation
# Copy the production template
cp .env.example .env
# Edit .env with your actual production values

🧪 Test Environment Configuration​

File: test/.env.test.example → test/.env.test (test directory)

  • Purpose: Test execution configuration only
  • Usage: Unit tests, integration tests, and E2E tests
  • Contains: Test-specific variables and test environment controls
# Copy the test template
cp test/.env.test.example test/.env.test
# Edit test/.env.test with your test values

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

Test Environment Loading​

During test execution, the test framework automatically loads from test/.env.test:

# Tests automatically use test/.env.test
uv run pytest

# Tests can be controlled with MCP_NO_ENV_FILE
MCP_NO_ENV_FILE=true uv run pytest  # Skip main .env file loading

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"

# CORS: Allow local development origins
CORS_ALLOW_ORIGINS="http://localhost:3000,http://localhost:8080"
CORS_ALLOW_CREDENTIALS="true"
CORS_ALLOW_METHODS="GET,POST,PUT,DELETE,OPTIONS"
CORS_ALLOW_HEADERS="Content-Type,Authorization,X-Requested-With"

Production Environment (.env.production)​

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

# CORS: Restrict to production domains
CORS_ALLOW_ORIGINS="https://app.yourdomain.com"
CORS_ALLOW_CREDENTIALS="true"
CORS_ALLOW_METHODS="GET,POST,PUT"
CORS_ALLOW_HEADERS="Content-Type,Authorization"

Testing Environment (test/.env.test)​

The test environment uses a separate configuration file to avoid conflicts with production settings:

# Test-specific configuration (test/.env.test)
E2E_TEST_API_TOKEN="xoxb-your-test-slack-bot-token"
SLACK_TEST_CHANNEL="#automated-testing"
SLACK_TEST_CHANNEL_ID="C9876543210"
MCP_NO_ENV_FILE=true
QUEUE_BACKEND="memory"

Key Test Environment Variables:

  • E2E_TEST_API_TOKEN: Bot token for end-to-end tests
  • SLACK_TEST_CHANNEL: Test channel name (with # prefix)
  • SLACK_TEST_CHANNEL_ID: Test channel ID (recommended over name)
  • MCP_NO_ENV_FILE=true: Prevents loading main .env file during tests
  • QUEUE_BACKEND="memory": Uses in-memory queue for test isolation

Test Environment Setup:

# Copy test environment template
cp test/.env.test.example test/.env.test

# Edit with your test values
nano test/.env.test

# Run tests (automatically uses test/.env.test)
uv run pytest
Test Environment Isolation

The test environment is designed to be completely isolated from production:

  • Uses test/.env.test instead of .env
  • MCP_NO_ENV_FILE=true prevents loading production settings
  • QUEUE_BACKEND="memory" ensures test isolation
  • Separate test channels avoid production data contamination

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​

# Production environment files
.env
.env.local
.env.development
.env.production

# Test environment files
test/.env.test
test/.env.test.local

# Backup env files
*.env.backup
Security Note

Both production (.env) and test (test/.env.test) environment files contain sensitive credentials and should never be committed to version control. Always add both to your .gitignore file.

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: