Gnosis Slackbot

An async Python-based Slackbot with Docker support and MCP tool integration.

Features

• 🤖 Async Slack bot using slack-bolt
• 🐳 Docker containerization for easy deployment
• 🔌 FastAPI-based API for external integrations
• 🛠️ MCP tool for Claude integration
• 📸 Support for text, images, and file uploads
• 🔄 Thread replies and rich message formatting

Documentation

All extended guides now live in the vibe/ directory:

• Setup Guide
• API Documentation
• Project Summary
• Operations Checklist

Quick Start

1. Installation

Run the interactive setup wizard:

python setup.py --install

This will prompt you for:

• Slack Bot Token (xoxb-...)
• Slack App Token (xapp-...)
• Slack Signing Secret
• Optional: Default channel ID
• API configuration

2. Build Docker Container

python setup.py --build

3. Start the Bot

python setup.py --start

On Windows (PowerShell):

scripts\start_bot.ps1

Or run locally without Docker:

python -m bot.main

Setup Slack App

1. Go to https://api.slack.com/apps

2. Create a new app (or use existing)

3. Configure Bot Token Scopes:

   • app_mentions:read
   • channels:history
   • channels:read
   • chat:write
   • files:write
   • im:history
   • im:read
   • im:write
   • users:read

4. Enable Socket Mode and get App Token

5. Install app to your workspace

6. Copy tokens and run python setup.py --install

API Usage

The bot exposes a REST API on port 8765 (configurable).

Send Message

curl -X POST http://localhost:8765/send \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "C1234567890",
    "text": "Hello from Gnosis!"
  }'

Send Image

curl -X POST http://localhost:8765/send-with-image \
  -F "channel=C1234567890" \
  -F "text=Check out this image!" \
  -F "image=@/path/to/image.png"

Reply to Thread

curl -X POST http://localhost:8765/reply \
  -F "channel=C1234567890" \
  -F "thread_ts=1234567890.123456" \
  -F "text=This is a reply"

MCP Tool Integration

The MCP tool allows Claude and other MCP clients to interact with Slack.

Setup MCP Tool

1. Install MCP dependencies:

cd mcp
pip install -r requirements.txt

2. Add to your MCP configuration (e.g., Claude Desktop config):

{
  "mcpServers": {
    "gnosis-slackbot": {
      "command": "python",
      "args": [
        "/path/to/gnosis-slackbot/mcp/slackbot_mcp.py"
      ]
    }
  }
}

Available MCP Tools

• slack_send_message - Send text messages
• slack_send_image - Send images
• slack_reply - Reply to threads
• slack_upload_file - Upload files
• slack_get_user - Get user info
• slack_get_channel - Get channel info

Message Logging & Monitoring

All outgoing bot messages (API sends, DM auto-replies, mention responses, slash command replies, and file uploads) are mirrored into logs/slack_messages.log. The log is newline-delimited JSON so it can be tailed by other agents.

• Configure the path with SLACK_MESSAGE_LOG (defaults to logs/slack_messages.log).
• Attachments uploaded through the bot are mirrored to logs/slack_messages/attachments/ (override with SLACK_ATTACHMENTS_DIR). Each log entry includes a local_copy field pointing to the saved file when available.
• Within the Codex container, the slack-log MCP server provides helpers:
  • slack_log_status — confirm the file exists and report size/mtime.
  • slack_log_tail — fetch the most recent entries.
  • slack_log_since — retrieve entries newer than an ISO timestamp.

Example tail command from the Codex CLI:

codex tool slack-log slack_log_tail '{"tail": 20}'

Docker Commands

View Logs

docker logs -f gnosis-slackbot

Stop Bot

python setup.py --stop

Or manually:

docker stop gnosis-slackbot
docker rm gnosis-slackbot

Rebuild and Restart

python setup.py --stop
python setup.py --build
python setup.py --start

Project Structure

gnosis-slackbot/
├── bot/
│   ├── __init__.py
│   ├── main.py           # Entry point
│   ├── slack_bot.py      # Slack bot logic
│   └── api_server.py     # FastAPI server
├── vibe/
│   ├── API_DOCUMENTATION.md
│   ├── CHECKLIST.md
│   ├── PROJECT_SUMMARY.md
│   └── SETUP_GUIDE.md
├── mcp/
│   ├── slackbot_mcp.py   # MCP tool implementation
│   └── requirements.txt
├── scripts/
│   ├── start_bot.sh      # Unix/macOS launcher
│   ├── start_bot.ps1     # Windows PowerShell launcher
│   ├── restart_container.sh
│   ├── check_channel_join.py
│   ├── test_container.py
│   └── test_send_message.py
├── Dockerfile
├── requirements.txt
├── setup.py              # Setup and management script
├── .env                  # Configuration (created by setup)
└── README.md

Configuration

All configuration is stored in .env:

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
SLACK_DEFAULT_CHANNEL=C1234567890
API_HOST=0.0.0.0
API_PORT=8765
DEBUG=false

Development

Run Locally

# Install dependencies
pip install -r requirements.txt

# Run bot
python -m bot.main

Debug Mode

Set DEBUG=true in .env for verbose logging.

Troubleshooting

Bot Not Responding

1. Check logs: docker logs gnosis-slackbot
2. Verify tokens in .env
3. Ensure Socket Mode is enabled in Slack app
4. Check bot has required scopes

API Not Accessible

1. Check if container is running: docker ps
2. Verify port mapping: -p 8765:8765
3. Check firewall settings

MCP Tool Issues

1. Verify API is running: curl http://localhost:8765/health
2. Check MCP tool configuration path
3. Review MCP logs

License

MIT

Support

For issues and questions, please create an issue in the repository.