# 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](https://docs.astral.sh/uv/) (recommended) or pip
- Slack Bot Token (`xoxb-...`) — required
- Slack User Token (`xoxp-...`) — optional, enables search features
## Installation
```bash
git clone https://github.com/software-engineer-mj/slack-mcp.git
cd slack-mcp
uv sync
```
## Configuration
```bash
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)
```bash
uv run python -m slack_mcp
```
### SSE transport
```bash
uv run python -m slack_mcp --transport=sse
```
### Streamable HTTP transport
```bash
uv run python -m slack_mcp --transport=streamable-http
```
### Docker
```bash
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:
```bash
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`:
```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`:
```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
```bash
# 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](LICENSE) for details.
