MCP Slack Agent Team

🚀 mcp-slack-agent-team

An MCP server for remote control of Claude Code and multi - agent team management based on Slack.

This project allows you to send commands to Claude Code agents in Slack channels, receive results, and coordinate multi - agent teams.

🚀 Quick Start

# 1. Clone & Install
git clone https://github.com/berrzebb/mcp-slack-agent-team.git
cd mcp-slack-agent-team/mcp-servers/slack
npm install
npm run build

# 2. Connection Test
cp .env.example .env
# Enter SLACK_BOT_TOKEN and SLACK_DEFAULT_CHANNEL in .env
npx tsx src/test.ts

Register with Claude Code

In .claude/settings.json or ~/.claude.json:

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["path/to/mcp-slack-agent-team/mcp-servers/slack/dist/wrapper.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
        "SLACK_DEFAULT_CHANNEL": "CchannelID"
      }
    }
  }
}

✨ Features

• Remote Control — Enter commands in Slack → Agents execute → Reply with results in threads.
• Command Loop — Completely replace the chat interface with slack_command_loop.
• Non - blocking Check — Use slack_command_loop(timeout = 0) and slack_team_wait(timeout = 0) to avoid missing Slack commands during work.
• Multi - agent Team — Create dedicated channels, assign names/icons by roles, broadcast messages, and archive channels.
• Agent Personas — 12 named personas (e.g., Aria, Sage, Forge) — Automatically display unique names/emojis by roles.
• @Mention System — Mention agents by persona names, roles, or member IDs → Store mentions in the queue → Recipients can check.
• Reaction - Command — Automatically convert Slack emoji reactions (✅❌🚀🔄🗑️❓) into commands.
• Background Collection — Automatically poll messages every 10 seconds to prevent losing Slack messages without tool calls.
• Multiprocess Safety — Use SQLite WAL + busy_timeout + poller DB lease + individual storage for each team.
• Permanent Context Management — Store task/decision/agent contexts based on SQLite, and restore contexts immediately after compression.
• Hot Reload — Build code and restart the server with slack_reload, and keep the Claude Code connection with wrapper.js.
• General Approval Hook — Support Bash commands, MCP tools, and permission requests. Automatically bypass safe commands.
• Rate Limiter — Centralized control of Slack API calls (token bucket + automatic backoff on 429).
• Dashboard — Visually display team progress, agent status, and Rate Limiter metrics on a dashboard.
• Heartbeat — Monitor agent survival, automatically detect and notify unresponsive agents.
• DM + Scheduled Messages — Send private DMs, schedule messages, and pin messages.
• Inbox Search — Search inbox messages with FTS5 full - text search.
• Graceful Shutdown — Automatically save the state and send Slack notifications on SIGINT/SIGTERM.
• File Transfer — Download/upload files (images, documents, logs, etc.) on Slack.
• Automatic Long Message Handling — Split and send long messages or upload them as files.
• Cost Reporting — Report Claude Code tokens/costs on Slack by integrating with ccusage.
• Session Recovery — Automatically restore the state after compacting/restarting.

📦 Installation

The installation steps are included in the "Quick Start" section.

💻 Usage Examples

Workflow

User (Slack)             Agent (Claude Code)
    │                            │
    ├─── Enter Command ────────────→│  slack_command_loop
    │                            ├── 👀 Confirm Receipt
    │                            ├── Perform Task
    │                            ├── Send Result (Thread)
    │←── Receive Result ────────────┤  ✅ Complete
    ├─── Provide Feedback ─────────────→│  slack_wait_for_reply
    │                            └── Wait for Next Command

📚 Documentation

Directory Structure

commands/                          # Claude Code slash commands
├── slack-loop.md                  #   /slack-loop — Slack command waiting loop
└── slack-team-resume.md           #   /slack-team-resume — Team session recovery

mcp-servers/slack/                 # Slack MCP server
├── src/
│   ├── index.ts                   #   Entry point (tool registration + server start)
│   ├── wrapper.ts                 #   Automatic restart wrapper (supports hot reload)
│   ├── background-poller.ts       #   Background message collector (every 10 seconds)
│   ├── types.ts                   #   Interface, constants, type definitions + agent personas
│   ├── db.ts                      #   SQLite initialization + data access helper
│   ├── state.ts                   #   SQLite-based state management + team registry
│   ├── slack-client.ts            #   WebClient + sendSmart + message splitting
│   ├── formatting.ts              #   Message formatting + rich formatting utilities
│   ├── rate-limiter.ts             #   Centralized Rate Limiter (token bucket + automatic backoff)
│   ├── approval-hook.ts           #   General Slack approval hook (Bash + tools + permissions)
│   ├── test.ts                    #   Connection test
│   ├── check.ts                   #   Simple connection check
│   └── tools/                     #   Tool modules (55 in total)
│       ├── basic.ts               #     Basic communication + reaction management + diagnostics (11)
│       ├── content.ts             #     Code/snippet upload (2)
│       ├── loop.ts                #     Command loop + inbox + reaction commands (3)
│       ├── team.ts                #     Team management + mentions + notification integration (14)
│       ├── context.ts             #     Team context management + whoami (8)
│       ├── approval.ts            #     Approval request (1)
│       ├── file.ts                #     File download/upload (2)
│       ├── state.ts               #     State save/restore + cost reporting (3)
│       └── dashboard.ts           #     Dashboard + heartbeat + DM + reservation/permissions (11)
├── package.json
├── tsconfig.json
└── .env.example

Available Tools (55)

Required Slack Bot Token Scopes

Detailed configuration guide: mcp-servers/slack/README.md

📄 License

MIT