Version: 0.0.2

Logging Configuration

This guide covers how to configure logging for both the Slack MCP Server and Slack Webhook Server, including command-line options, environment variables, and file logging.

Quick Start

Basic Logging

By default, both servers log to console with INFO level:

MCP Server
Webhook Server

# Using UV
uv run slack-mcp-server

# Using console script
slack-mcp-server

# Using Python module
python -m slack_mcp.mcp

# Using UV
uv run slack-webhook-server

# Using console script
slack-webhook-server

# Using Python module
python -m slack_mcp.webhook

Debug Logging

Enable detailed logging for troubleshooting (works for both servers):

MCP Server
Webhook Server

# Case-insensitive - all these work
uv run slack-mcp-server --log-level debug
uv run slack-mcp-server --log-level DEBUG
slack-mcp-server --log-level info

# Case-insensitive - all these work
uv run slack-webhook-server --log-level debug
uv run slack-webhook-server --log-level DEBUG
slack-webhook-server --log-level info

File Logging

Write logs to a file with automatic rotation (works for both servers):

MCP Server
Webhook Server

slack-mcp-server \
  --log-level info \
  --log-file /var/log/slack-mcp.log

slack-webhook-server \
  --log-level info \
  --log-file /var/log/slack-webhook.log

Command-Line Options

Log Level

Control the verbosity of log output:

# Case-insensitive - all these work
slack-mcp-server --log-level debug    # Most verbose
slack-mcp-server --log-level info     # General information
slack-mcp-server --log-level warning  # Warnings only
slack-mcp-server --log-level error    # Errors only
slack-mcp-server --log-level critical # Critical errors only

Case-Insensitive

You can use any case: debug, DEBUG, Debug, DeBuG - they all work the same way!

Available Log Levels:

Level	Description	Use Case
`DEBUG`	Detailed diagnostic information	Development and troubleshooting
`INFO`	General informational messages	Production monitoring
`WARNING`	Warning messages	Potentially problematic situations
`ERROR`	Error messages	Serious problems
`CRITICAL`	Critical error messages	Fatal problems

Log File

Specify a log file to write logs alongside console output:

# Absolute path
slack-mcp-server --log-file /var/log/slack-mcp.log

# Relative path (uses --log-dir)
slack-mcp-server --log-file slack-mcp.log

Features:

Automatic Rotation: Files rotate at 10MB
Backup Files: Keeps 5 backup files
Dual Output: Logs to both console and file simultaneously

Log Directory

Set the directory for log files when using relative paths:

slack-mcp-server \
  --log-dir /var/log/slack-mcp \
  --log-file server.log
# Logs to: /var/log/slack-mcp/server.log

Default: logs/ in current working directory

Log Format

Customize the log message format:

slack-mcp-server \
  --log-format "%(asctime)s [%(levelname)s] %(name)s: %(message)s"

Default Format: %(asctime)s [%(levelname)8s] %(name)s: %(message)s

Format Variables:

%(asctime)s - Timestamp
%(levelname)s - Log level (DEBUG, INFO, etc.)
%(name)s - Logger name (module path)
%(message)s - Log message
%(lineno)d - Line number
%(funcName)s - Function name

Environment Variables

Configure logging via environment variables:

# Set log level
export LOG_LEVEL=debug

# Set log file
export LOG_FILE=/var/log/slack-mcp.log

# Set log directory
export LOG_DIR=/var/log

# Set log format
export LOG_FORMAT="%(asctime)s %(levelname)s: %(message)s"

# Run server (uses environment variables)
slack-mcp-server

Priority

Command-line arguments override environment variables.

Common Use Cases

Development

Enable verbose logging for development:

Command Line
Environment Variables

uv run slack-mcp-server \
  --transport stdio \
  --log-level debug

export LOG_LEVEL=debug
uv run slack-mcp-server --transport stdio

Production

Production configuration with file logging:

slack-mcp-server \
  --transport sse \
  --host 0.0.0.0 \
  --port 3001 \
  --log-level info \
  --log-file /var/log/slack-mcp/server.log \
  --log-dir /var/log/slack-mcp

Docker Container

Configure logging for containerized deployments:

# Dockerfile
ENV LOG_LEVEL=info
ENV LOG_FORMAT="%(asctime)s %(levelname)s: %(message)s"

CMD ["slack-mcp-server", "--transport", "sse"]

# Docker run
docker run -e LOG_LEVEL=debug slack-mcp-server

Systemd Service

Configure logging in a systemd service:

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

[Service]
Type=simple
User=slack-mcp
Environment="LOG_LEVEL=info"
Environment="LOG_FILE=/var/log/slack-mcp/server.log"
ExecStart=/usr/local/bin/slack-mcp-server --transport sse --host 0.0.0.0
Restart=on-failure

[Install]
WantedBy=multi-user.target

Testing

Enable verbose logging for test troubleshooting:

# Temporary verbose logging
slack-mcp-server --log-level debug --transport stdio

# Or with environment variable
LOG_LEVEL=debug slack-mcp-server --transport stdio

Log File Management

Rotation Behavior

Log files automatically rotate when they reach 10MB:

slack-mcp.log           # Current log
slack-mcp.log.1         # Most recent backup
slack-mcp.log.2         # Second most recent
slack-mcp.log.3
slack-mcp.log.4
slack-mcp.log.5         # Oldest backup (deleted on next rotation)

Custom Log Location

Organize logs by environment or server type:

# Development
slack-mcp-server \
  --log-file /var/log/slack-mcp/dev-server.log \
  --log-level debug

# Production
slack-mcp-server \
  --log-file /var/log/slack-mcp/prod-server.log \
  --log-level info

# By date
slack-mcp-server \
  --log-file "/var/log/slack-mcp/server-$(date +%Y%m%d).log"

External Libraries

The logging system automatically reduces noise from external libraries:

Silenced Libraries (ERROR level only):

uvicorn - ASGI server logs
httpx - HTTP client logs
asyncio - Async event loop logs

This keeps your logs clean and focused on your application logic.

Monitoring and Analysis

Log Patterns

Common log patterns to monitor:

# Watch for errors
tail -f /var/log/slack-mcp.log | grep ERROR

# Monitor specific module
tail -f /var/log/slack-mcp.log | grep "slack_mcp.mcp"

# Count log levels
cat /var/log/slack-mcp.log | grep -o '\[.*\]' | sort | uniq -c

Integration with Log Aggregators

The structured log format works well with log aggregation tools:

Fluentd:

<source>
  @type tail
  path /var/log/slack-mcp/*.log
  tag slack.mcp
  format /^(?<time>[^ ]*) \[(?<level>[^\]]*)\] (?<logger>[^:]*): (?<message>.*)$/
</source>

Logstash:

filter {
  grok {
    match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} \[%{LOGLEVEL:level}\] %{DATA:logger}: %{GREEDYDATA:message}" }
  }
}

Troubleshooting

No Log Output

If logs aren't appearing:

Check log level: Ensure messages match the configured level
```
slack-mcp-server --log-level debug  # Most verbose
```

Verify file permissions: Ensure write permissions for log files

chmod 755 /var/log/slack-mcp
touch /var/log/slack-mcp/server.log
chmod 644 /var/log/slack-mcp/server.log

Check environment variables: Command-line args override env vars

# Clear environment variables
unset LOG_LEVEL LOG_FILE
slack-mcp-server --log-level debug

Log File Not Rotating

If log rotation isn't working:

Check file size: Rotation occurs at 10MB
```
ls -lh /var/log/slack-mcp/
```
Verify write permissions: Server needs permission to create backup files
Check disk space: Ensure sufficient space for rotation
```
df -h /var/log
```

Performance Impact

High log levels can impact performance:

DEBUG: Use only in development or troubleshooting
INFO: Good for production with moderate traffic
WARNING: Minimal impact, recommended for high-traffic production

Best Practices

Use INFO in production: Balances detail with performance
Enable file logging: Always log to files in production
Monitor log files: Set up alerts for ERROR and CRITICAL logs
Use case-insensitive: Write --log-level debug for better readability
Rotate logs: Let the automatic rotation handle file management
Structured formats: Use consistent log formats for parsing
Environment-specific levels: DEBUG for dev, INFO for production

Next Steps

MCP Server CLI Reference - MCP server command-line options
Webhook Server CLI Reference - Webhook server command-line options
Deployment Guide - Production deployment patterns
Environment Configuration - Environment variables reference

Quick Start​

Basic Logging​

Debug Logging​

File Logging​

Command-Line Options​

Log Level​

Log File​

Log Directory​

Log Format​

Environment Variables​

Common Use Cases​

Development​

Production​

Docker Container​

Systemd Service​

Testing​

Log File Management​

Rotation Behavior​

Custom Log Location​

External Libraries​

Monitoring and Analysis​

Log Patterns​

Integration with Log Aggregators​

Troubleshooting​

No Log Output​

Log File Not Rotating​

Performance Impact​

Best Practices​

Next Steps​