Tiger Slack

What is Tiger Slack about?

Tiger Slack delivers conversational memory for AI Slack bots by continuously ingesting Slack messages, reactions, and metadata into a TimescaleDB instance and exposing that data through an MCP server. AI agents can query the server to retrieve full thread context, user participation, and channel information, enabling responses that reflect the team's ongoing discussions.

How to use Tiger Slack?

1. Clone the repository with submodules.
2. Configure a Slack App (tokens in .env).
3. Run the Docker Compose stack (docker compose up -d --build).
4. Connect an MCP client (e.g., Claude Code or MCP Inspector) to http://localhost:3001/mcp.
5. Query the server using MCP methods such as listChannels, getConversation, or generatePermalink.

Key Features

• Real‑time WebSocket (Socket Mode) ingestion of messages, reactions, user and channel updates.
• Support for loading historic Slack exports.
• TimescaleDB storage with 7‑day chunking, automatic compression, sparse indexes, and full‑text search.
• MCP HTTP server offering AI‑friendly APIs for browsing channels, retrieving threaded conversations, and generating permalinks.
• Observability via Logfire (tracing, metrics, error tracking).
• Docker‑compose deployment for quick start and easy orchestration.

Use Cases

• AI assistants that answer questions about past decisions, project timelines, or who is responsible for a topic.
• Automated knowledge bases that surface relevant Slack threads when a user asks a query.
• Analytics dashboards built on top of the TimescaleDB schema to visualize team communication patterns.
• Compliance audits that need searchable archives of Slack conversations.
• Real‑time bots that proactively suggest actions based on recent channel activity.

FAQ

Q: Do I need a TimescaleDB license? A: TimescaleDB is open source; you can run the provided Docker image without a commercial license.

Q: Which Slack permissions are required? A: The app needs connections:write, chat:write, channels:history, reactions:read, users:read, and related scopes defined in the manifest.

Q: Can I run the MCP server without Docker? A: Yes. After building the TypeScript code (npm run build or bun run build), start it with node dist/index.js and set the required PostgreSQL environment variables.

Q: How does compression work? A: After 45 days, TimescaleDB automatically compresses chunks, achieving 5‑10× space savings while keeping queries fast.

Q: Is there a way to reset the database? A: Use docker compose down -v to remove volumes, which clears all stored Slack data.

Tiger Slack

Conversational Memory for AI Slack Bots

Tiger Slack gives Slack-native AI assistants the ability to understand and engage with your team's conversations naturally. By providing real-time access to Slack message history and context through an MCP server, it enables AI bots to respond to questions with the same contextual awareness that humans have - understanding references to past discussions, ongoing projects, and team dynamics.

Tiger Slack is the superpower behind Eon, TigerData's Slack-native AI assistant.

Ready to get started? Jump to the quick start.

Overview

Built for teams who want their AI assistants to:

• Understand conversational context and references to past discussions
• Answer questions about project history and decisions
• Know who's involved in different topics and threads
• Follow ongoing conversations and provide relevant input
• Build conversational memory across all team channels

Key Components

Ingest Service (ingest/)

The ingest service is a Python app that:

• Connects to Slack via WebSocket (Socket Mode)
• Captures messages, reactions, user changes, and channel updates in real-time
• Runs scheduled jobs for user/channel synchronization

The ingest service can process a Slack historical export into the database.

See the ingest README.md for more details.

MCP Server (mcp/)

A Streamable HTTP Model Context Protocol server provides:

• AI-accessible APIs for Slack data analysis
• Channel and user browsing with intelligent filtering
• Conversation retrieval with full threading context
• Message permalink generation

See the mcp README.md for more details.

###️TimescaleDB Database Tiger Slack uses a TimescaleDB database to store the Slack content.

• High-throughput message ingestion with 7-day chunk partitioning
• Efficient time-based queries and analytics
• Automatic compression after 45 days (5-10x space savings)
• Channel-based segmentation for optimal query performance
• Sparse indexes (bloom filters, minmax) for fast filtering
• Chunk skipping for accelerated thread queries
• Full-text search capabilities across message content

Architecture

Quick Start

Start by cloning the repo.

git clone --recurse-submodules git@github.com:timescale/tiger-slack.git
cd tiger-slack

The ingest service requires an app configured in Slack with proper privileges and tokens. You can run a script to automate this setup, or you can do it manually.

Automated Setup

Execute the following script to guide you through the setup process:

./setup-tiger-slack.sh

Manual Setup

Create a Slack App

1. Edit the slack-app-manifest.json file to have the names and descriptions you want to use.
2. Create a new Slack app
3. Choose to create an app from a manifest.
4. Pick your workspace and click Next.
5. Paste that manifest configuration in the input field provided and click Next.
6. Review and verify that the configuration you entered matches the summary and click Create.
7. Navigate to: Basic Information → App-Level Tokens
8. Click 'Generate Token and Scopes' → Add 'connections:write' scope → Generate
9. Save your SLACK_APP_TOKEN (It starts with xapp-).
10. Navigate to: Install App → Click 'Install to [Workspace]'
11. After installation, save the 'Bot User OAuth Token' A.K.A. SLACK_BOT_TOKEN (It starts with xoxb-)

cp .env.sample .env

Add the Slack tokens to the .env file.

Running the System

After setting up the .env file, you are ready to run the system!

Build and run the system in docker compose:

docker compose up -d --build

Other system lifecycle commands

docker compose up -d          # Start all services in background
docker compose down           # Stop all services
docker compose build          # Build all images
docker compose logs -f        # View live logs from all services
docker compose restart        # Restart all services

# Reset with fresh volumes (deletes all data)
docker compose down -v
docker compose up -d

# Nuclear reset (complete cleanup)
docker compose down -v --remove-orphans
docker system prune -f --volumes
docker compose up -d --build

Dev/Test Exploration

Use Claude Code and/or the MCP Inspector to exercise the MCP Server.

Using Claude Code

1. Connect Claude Code to the MCP Server

   To connect to the MCP server running in docker, run:

   claude mcp add -s project --transport http tiger-slack http://localhost:3001/mcp
   

   To use the MCP server via stdio (not docker), run this after building the mcp:

   export PGHOST=localhost
   export PGPORT=5432
   export PGUSER=tsdbadmin
   export PGDATABASE=tsdb
   export LOGFIRE_TOKEN=<your-logfire-token> # optional. sends traces from the mcp server to logfire
   claude mcp add -s project tiger-slack node /absolute/path/to/tiger-slack/mcp/dist/index.js stdio
   

2. Connect to Logfire (Optional) Giving Claude Code the ability to "see" the tracing data for the project can drive powerful AI insights.

   claude mcp add -s project logfire -e LOGFIRE_READ_TOKEN="your-token-here" -- uvx logfire-mcp@latest
   

3. Start Analyzing Ask Claude: "Show me recent conversations in #engineering"

Using MCP Inspector

You can use the MCP Inspector to interact with the MCP server via a web UI. Run the following from the mcp directory:

./bun run inspector

Suggested Roll-out Strategy

1. First, use a manual execution of the user/channel jobs to create the database schema and populate the users and channels.
2. Deploy the ingest service to begin accumulating Slack events in real-time.
3. At some point after you have begun accumulating new Slack events in real time, get a historical export from Slack and load it with the import process.

This strategy ensures no gaps in data.

Observability Stack

Tiger Slack features full-stack monitoring via Logfire integration:

• Distributed tracing across all components
• Real-time performance metrics
• Error tracking and debugging
• AI-powered log analysis via MCP and Claude Code

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Transform your Slack workspace into an intelligent knowledge base with AI-powered analytics and insights.