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:

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:

Additional scope required for User Token:

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)

Messages (5)

Users (4)

Files (3)

Reactions (2)

MCP Resources

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.