Slack MCP Server

An MCP (Model Context Protocol) server that exposes the Slack API, enabling AI agents (Claude, Cursor, etc.) to interact with Slack directly.

Provides 20 tools and 2 resources with focused Slack API coverage.

Features

• 20 MCP Tools — channels, messages, users, files, and reactions
• 2 MCP Resources — slack://channels and slack://users for workspace discovery
• Rate Limit Handling — automatic retry with Retry-After backoff via slack_sdk built-in handlers
• Safety Controls — channel whitelist for message-sending restrictions, write tools disabled by default
• Conditional Tool Registration — search tools auto-disabled when User Token is not provided
• Block Kit Support — all message tools accept Block Kit JSON
• Multiple Transports — stdio (default), SSE, and streamable-http
• Docker Support — production-ready Dockerfile included

Requirements

• Python >= 3.10
• uv (recommended) or pip
• Slack Bot Token (xoxb-...) — required
• Slack User Token (xoxp-...) — optional, enables search features

Installation

git clone https://github.com/software-engineer-mj/slack-mcp.git
cd slack-mcp
uv sync

Configuration

cp .env.example .env

Edit the .env file and fill in your tokens:

Variable	Required	Description
SLACK_BOT_TOKEN	Yes	Bot token (xoxb-...)
SLACK_USER_TOKEN	No	User token (xoxp-...) for search features
SLACK_MCP_LOG_LEVEL	No	Log level: DEBUG, INFO (default), WARNING, ERROR
SLACK_MCP_ALLOWED_CHANNELS	No	Comma-separated channel IDs to restrict message sending (e.g., C123,C456). Default: all channels allowed

Safety Controls

Channel Whitelist: When SLACK_MCP_ALLOWED_CHANNELS is set, message-sending tools (send_message, reply_to_thread, update_message) are restricted to the listed channels only.

Slack App Permissions (Bot Token Scopes)

The Bot Token requires the following OAuth scopes:

Scope	Purpose
channels:read	List and view channel info
channels:history	Read channel message history
groups:read	View private channels
groups:history	Read private channel history
chat:write	Send and update messages
im:read	View direct messages
im:history	Read DM history
im:write	Open DMs
mpim:read	View group DMs
mpim:history	Read group DM history
users:read	View user info
users:read.email	Look up users by email
users.profile:read	View user profiles
reactions:read	View reactions
reactions:write	Add reactions
files:read	View files
files:write	Upload files

Additional scope required for User Token:

Scope	Purpose
search:read	Search messages and files

Usage

stdio (default)

uv run python -m slack_mcp

SSE transport

uv run python -m slack_mcp --transport=sse

Streamable HTTP transport

uv run python -m slack_mcp --transport=streamable-http

Docker

docker build -t slack-mcp .

docker run -e SLACK_BOT_TOKEN=xoxb-your-token \
           -e SLACK_USER_TOKEN=xoxp-your-token \
           slack-mcp

To restrict channels:

docker run -e SLACK_BOT_TOKEN=xoxb-your-token \
           -e SLACK_MCP_ALLOWED_CHANNELS=C123,C456 \
           slack-mcp

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/slack-mcp", "python", "-m", "slack_mcp"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_USER_TOKEN": "xoxp-your-token"
      }
    }
  }
}

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/slack-mcp", "python", "-m", "slack_mcp"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_USER_TOKEN": "xoxp-your-token"
      }
    }
  }
}

Development

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

Available Tools (20)

Channels (6)

Tool	Description
list_channels	List channels (with cursor pagination support)
get_channel_info	Get channel details
get_channel_history	Read channel message history
get_channel_members	List channel members (with cursor pagination support)
get_channel_summary	Summarize recent activity (resolved names + threads)
open_conversation	Open a DM conversation

Messages (5)

Tool	Description
send_message	Send a message (supports Block Kit)
reply_to_thread	Reply to a thread (supports Block Kit)
get_thread_replies	Get thread replies
update_message	Update a message (supports Block Kit)
search_messages	Search messages (requires User Token)

Users (4)

Tool	Description
list_users	List users (with cursor pagination support)
get_user_info	Get user details (cached)
get_user_profile	Get user profile
lookup_user_by_email	Look up a user by email

Files (3)

Tool	Description
list_files	List files (with page-based pagination)
upload_file	Upload a file
search_files	Search files (requires User Token)

Reactions (2)

Tool	Description
add_reaction	Add an emoji reaction
list_reactions	Get all reactions on a message

MCP Resources

URI	Description
slack://channels	CSV list of all channels (id, name, is_private, num_members)
slack://users	CSV list of all users (id, name, real_name, is_bot, deleted)

Project Structure

src/slack_mcp/
├── __init__.py          # FastMCP server instance
├── __main__.py          # Entry point with auto-discovery
├── client.py            # SlackClient singleton (API calls, error handling, pagination)
├── exceptions.py        # Custom exception hierarchy
├── lifespan.py          # Server lifecycle (conditional tool registration, safety controls)
├── resources.py         # MCP resources (channels, users)
└── tools/
    ├── __init__.py
    ├── channels.py      # Channels
    ├── files.py         # Files
    ├── messages.py      # Messages (Block Kit support)
    ├── reactions.py     # Reactions
    └── users.py         # Users
tests/
├── conftest.py          # Shared fixtures (mock Slack clients)
├── test_client.py       # SlackClient tests (error handling, pagination, safety)
├── test_exceptions.py   # Exception hierarchy tests
├── test_pagination.py   # Pagination utility tests
├── test_resources.py    # MCP resource tests
└── tools/
    ├── test_channels.py
    ├── test_files.py
    ├── test_messages.py
    ├── test_reactions.py
    └── test_users.py

License

MIT - see LICENSE for details.