slack

claude-code-slack

Slack channel plugin for Claude Code. Interact with Claude Code agents via Slack — no terminal needed.

How it works

This plugin runs as an MCP server alongside Claude Code. It connects to Slack via Socket Mode (WebSocket) and bridges messages between Slack and Claude Code. Claude Code sees Slack messages as channel notifications and can reply, react, edit messages, fetch history, and handle file attachments.

Prerequisites

Bun

This plugin requires Bun as its JavaScript runtime.

macOS / Linux:

curl -fsSL https://bun.sh/install | bash

Windows (via PowerShell):

irm bun.sh/install.ps1 | iex

Verify installation:

bun --version

If bun is not installed, the plugin will fail to start. See bun.sh for alternative install methods (Homebrew, npm, Docker, etc).

Claude Code

Version 2.1.80 or later is required (channels support). Check with:

claude --version

Important: Channels require a Claude Pro, Max, Team, or Enterprise subscription (claude.ai account login). API key authentication (ANTHROPIC_API_KEY) alone is not sufficient — the channels feature depends on claude.ai OAuth which is only available with a subscription plan. On headless servers without browser access (e.g. EC2), set CLAUDE_TMUX_WINDOW to use the tmux fallback delivery instead.

Slack App

You need a Slack app with Socket Mode enabled. Follow the steps below to create one.

Setup

1. Create a Slack App

1. Go to api.slack.com/apps and click Create New App
2. Choose From scratch, name it (e.g. "Claude"), and select your workspace
3. Go to Settings > Socket Mode and toggle it on
4. Generate an App-Level Token with the connections:write scope — this is your xapp- token. Save it.

2. Configure Bot Permissions

Go to OAuth & Permissions > Bot Token Scopes and add:

Scope	Purpose
app_mentions:read	Receive @bot mentions in channels
chat:write	Send messages
channels:read	Look up public channel metadata
channels:history	Read public channel history
groups:history	Read private channel history
im:history	Read DM history
mpim:history	Read group DM history
reactions:write	Add emoji reactions
files:write	Upload file attachments
files:read	Read file metadata
users:read	Resolve user IDs to display names (fetch_messages, fetch_thread)
users.profile:read	Read profile.display_name for name resolution

All scopes are required. Reinstall the app after adding any of them — the bot token issued at install time is scope-locked. If a scope is missing, the plugin does not crash: it silently falls back (e.g. fetch_messages prints raw U0… IDs instead of display names). Check plugin stderr for resolveUserName(…) failed: missing_scope to diagnose scope gaps.

3. Subscribe to Events

Go to Event Subscriptions and enable it. Under Subscribe to bot events, add all of the following:

Event	Purpose
message.channels	Receive messages in public channels
message.groups	Receive messages in private channels
message.im	Receive direct messages
message.mpim	Receive group direct messages
app_mention	Receive @mentions in channels

All five events are required. Socket Mode connects successfully without them, but Slack will never send message events over the WebSocket — the bot will appear online but silently ignore all messages.

4. Install the App to Your Workspace

Click Install App in the sidebar. After installing, copy the Bot User OAuth Token (xoxb-).

If you change scopes or event subscriptions after installing, you must reinstall the app for changes to take effect.

You now have two tokens:

• xoxb-... — Bot User OAuth Token (from Install App page)
• xapp-... — App-Level Token (from Socket Mode settings)

5. Install the Plugin

claude /install-plugin https://github.com/reef-digital/claude-code-slack

Or manually clone and add to your Claude Code MCP config:

git clone https://github.com/reef-digital/claude-code-slack.git

Then add to your MCP settings (e.g. ~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "slack": {
      "command": "bun",
      "args": ["run", "--cwd", "/path/to/claude-code-slack", "--silent", "start"]
    }
  }
}

Note: Do not use a cwd field in the MCP config — Claude Code ignores it. Use bun's --cwd flag in the args array instead.

6. Configure Tokens and Baseline Access

The plugin is configured entirely via environment variables — no JSON files to edit.

Run in Claude Code:

/slack:configure