{"id":31814420,"url":"https://github.com/timescale/tiger-slack","last_synced_at":"2025-10-11T08:49:16.493Z","repository":{"id":314154769,"uuid":"1049260704","full_name":"timescale/tiger-slack","owner":"timescale","description":"Real-time Slack ingest and MCP server to power your agentic Slack bots","archived":false,"fork":false,"pushed_at":"2025-10-03T21:34:17.000Z","size":292,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T21:38:15.685Z","etag":null,"topics":["agentic-ai","mcp-server","slackbot","timescaledb"],"latest_commit_sha":null,"homepage":"https://www.tigerdata.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timescale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T18:04:52.000Z","updated_at":"2025-10-03T19:57:55.000Z","dependencies_parsed_at":"2025-09-10T23:36:15.109Z","dependency_job_id":"f4a851c2-1422-48fb-b202-1784af47a21d","html_url":"https://github.com/timescale/tiger-slack","commit_stats":null,"previous_names":["timescale/tiger-slack"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/timescale/tiger-slack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftiger-slack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftiger-slack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftiger-slack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftiger-slack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timescale","download_url":"https://codeload.github.com/timescale/tiger-slack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftiger-slack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006644,"owners_count":26084150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","mcp-server","slackbot","timescaledb"],"created_at":"2025-10-11T08:49:15.549Z","updated_at":"2025-10-11T08:49:16.486Z","avatar_url":"https://github.com/timescale.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Tiger Slack\n\n**Conversational Memory for AI Slack Bots**\n\nTiger 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.\n\nTiger Slack is the superpower behind [Eon](https://github.com/timescale/tiger-eon), TigerData's Slack-native AI assistant.\n\nReady to get started? Jump to the [quick start](#quick-start).\n\n## Overview\n\nBuilt for teams who want their AI assistants to:\n- **Understand conversational context** and references to past discussions\n- **Answer questions about project history** and decisions\n- **Know who's involved** in different topics and threads\n- **Follow ongoing conversations** and provide relevant input\n- **Build conversational memory** across all team channels\n\n## Key Components\n\n### **Ingest Service** (`ingest/`)\n\nThe ingest service is a Python app that:\n- Connects to Slack via WebSocket (Socket Mode)\n- Captures messages, reactions, user changes, and channel updates in real-time\n- Runs scheduled jobs for user/channel synchronization\n\nThe ingest service can process a Slack historical export into the database.\n\nSee the [ingest README.md](/ingest/README.md) for more details.\n\n### **MCP Server** (`mcp/`)\nA Streamable HTTP Model Context Protocol server provides:\n- AI-accessible APIs for Slack data analysis\n- Channel and user browsing with intelligent filtering\n- Conversation retrieval with full threading context\n- Message permalink generation\n\nSee the [mcp README.md](/mcp/README.md) for more details.\n\n###️**TimescaleDB Database**\nTiger Slack uses a TimescaleDB database to store the Slack content.\n- High-throughput message ingestion with 7-day chunk partitioning\n- Efficient time-based queries and analytics\n- Automatic compression after 45 days (5-10x space savings)\n- Channel-based segmentation for optimal query performance\n- Sparse indexes (bloom filters, minmax) for fast filtering\n- Chunk skipping for accelerated thread queries\n- Full-text search capabilities across message content\n\n## Architecture\n\n```mermaid\ngraph TB\n    %% External Systems\n    S[Slack Workspace]\n    C[Claude/LLM Client]\n    \n    %% Core Components  \n    I[Ingest Service\u003cbr/\u003ePython]\n    D[TimescaleDB\u003cbr/\u003eTime-series Database]\n    M[MCP/HTTP Server\u003cbr/\u003eTypeScript]\n    \n    %% Data Flow - Ingestion\n    S --\u003e|WebSocket Events| I\n    S --\u003e|Historical Export| I\n    I --\u003e|Store Events| D\n    \n    %% Data Flow - Analysis\n    C --\u003e|MCP Protocol| M\n    M --\u003e|SQL Queries| D\n    M --\u003e|Structured Data| C\n```\n\n## Quick Start\n\nStart by cloning the repo.\n\n```bash\ngit clone --recurse-submodules git@github.com:timescale/tiger-slack.git\ncd tiger-slack\n```\n\nThe ingest service requires an app configured in Slack with proper privileges and tokens.\nYou can run a script to [automate this setup](#automated-setup), or you can [do it manually](#manual-setup).\n\n### Automated Setup\n\nExecute the following script to guide you through the setup process:\n\n```bash\n./setup-tiger-slack.sh\n```\n\n### Manual Setup\n\nCreate a Slack App\n\n1. Edit the [slack-app-manifest.json](/slack-app-manifest.json) file to have the names and descriptions you want to use.\n2. [Create a new Slack app](https://api.slack.com/apps?new_app=1)\n3. Choose to create an app **from a manifest**.\n4. Pick your workspace and click `Next`.\n5. Paste that manifest configuration in the input field provided and click `Next`.\n6. Review and verify that the configuration you entered matches the summary and click `Create`.\n7. Navigate to: Basic Information → App-Level Tokens\n8. Click 'Generate Token and Scopes' → Add 'connections:write' scope → Generate\n9. Save your `SLACK_APP_TOKEN` (It starts with `xapp-`).\n10. Navigate to: Install App → Click 'Install to [Workspace]'\n11. After installation, save the 'Bot User OAuth Token' A.K.A. `SLACK_BOT_TOKEN` (It starts with `xoxb-`)\n\n```bash\ncp .env.sample .env\n```\n\nAdd the Slack tokens to the .env file.\n\n\n### Running the System\n\nAfter setting up the .env file, you are ready to run the system!\n\nBuild and run the system in docker compose:\n\n```bash\ndocker compose up -d --build\n```\n\n#### Other system lifecycle commands\n\n```bash\ndocker compose up -d          # Start all services in background\ndocker compose down           # Stop all services\ndocker compose build          # Build all images\ndocker compose logs -f        # View live logs from all services\ndocker compose restart        # Restart all services\n\n# Reset with fresh volumes (deletes all data)\ndocker compose down -v\ndocker compose up -d\n\n# Nuclear reset (complete cleanup)\ndocker compose down -v --remove-orphans\ndocker system prune -f --volumes\ndocker compose up -d --build\n```\n\n## Dev/Test Exploration\n\nUse [Claude Code](https://www.claude.com/product/claude-code) and/or the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to exercise the MCP Server.\n\n### Using Claude Code\n\n1. **Connect Claude Code to the MCP Server**\n\n   To connect to the MCP server running in docker, run:\n\n   ```bash\n   claude mcp add -s project --transport http tiger-slack http://localhost:3001/mcp\n   ```\n\n   To use the MCP server via stdio (not docker), run this after building the mcp:\n\n   ```bash\n   export PGHOST=localhost\n   export PGPORT=5432\n   export PGUSER=tsdbadmin\n   export PGDATABASE=tsdb\n   export LOGFIRE_TOKEN=\u003cyour-logfire-token\u003e # optional. sends traces from the mcp server to logfire\n   claude mcp add -s project tiger-slack node /absolute/path/to/tiger-slack/mcp/dist/index.js stdio\n   ```\n\n2. **Connect to Logfire (Optional)**\n   Giving Claude Code the ability to \"see\" the tracing data for the project can drive powerful AI insights.\n\n   ```bash\n   claude mcp add -s project logfire -e LOGFIRE_READ_TOKEN=\"your-token-here\" -- uvx logfire-mcp@latest\n   ```\n\n4. **Start Analyzing**\n   Ask Claude: *\"Show me recent conversations in #engineering\"*\n\n### Using MCP Inspector\n\nYou can use the MCP Inspector to interact with the MCP server via a web UI. Run the following from the [mcp](/mcp) directory:\n\n```bash\nnpm run inspector\n```\n\n## Suggested Roll-out Strategy\n\n1. First, use a [manual execution of the user/channel jobs](/ingest/README.md#manual-job-execution) to create the database schema and populate the users and channels.\n2. [Deploy the ingest service](/ingest/README.md#running-the-ingest-service) to begin accumulating Slack events in real-time.\n3. 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](/ingest/README.md#historical-data-import).\n\nThis strategy ensures no gaps in data.\n\n## **Observability Stack**\nTiger Slack features full-stack monitoring via Logfire integration:\n- Distributed tracing across all components\n- Real-time performance metrics\n- Error tracking and debugging\n- AI-powered log analysis via MCP and Claude Code\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n*Transform your Slack workspace into an intelligent knowledge base with AI-powered analytics and insights.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Ftiger-slack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimescale%2Ftiger-slack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Ftiger-slack/lists"}