# Slack MCP Server

<!-- mcp-name: io.github.workos/slack-mcp-server -->

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Slack workspace operations. Connect any AI agent to Slack — send messages, manage channels, search conversations, react to messages, upload files, and look up user profiles.

**This is an independent, generalized MCP server.** It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

## Features

- 📨 **Messaging**: Send messages, read channels, reply to threads, send DMs
- 📁 **Channels**: List, create, archive channels, set topics
- 🔍 **Search**: Full-text search across workspace messages
- 😀 **Reactions**: Add/remove emoji reactions, pin/unpin messages
- 👤 **Users**: Look up user profiles (name, email, title, status)
- 📎 **Files**: Upload text files to channels

## Installation

**Recommended — no pre-install required (uses [uv](https://docs.astral.sh/uv/)):**
```bash
# uv manages a temporary isolated environment automatically
uvx --from workos-slack-mcp-server slack-mcp-server
```

**Or install permanently with pip:**
```bash
pip install workos-slack-mcp-server
```

**Or install from source:**
```bash
git clone https://github.com/workos/workos-slack-mcp-server
cd workos-slack-mcp-server
pip install -e .
```

## Quick Start

```bash
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_USER_TOKEN="xoxp-your-user-token"      # Optional, for search
export SLACK_SIGNING_SECRET="your-signing-secret"    # Optional, for verification

# Recommended: run via uvx (no install needed)
uvx --from workos-slack-mcp-server slack-mcp-server

# Or if installed via pip
slack-mcp-server

# Or run as a Python module
python -m slack_mcp_server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SLACK_BOT_TOKEN` | ✅ Yes | Bot User OAuth Token (`xoxb-...`) |
| `SLACK_USER_TOKEN` | ⬜ No | User OAuth Token (`xoxp-...`) — enables broader search results |
| `SLACK_SIGNING_SECRET` | ⬜ No | App Signing Secret — for request verification |

### Getting Slack Tokens

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Under **OAuth & Permissions**, add Bot Token Scopes:
   - `channels:read`, `channels:write`, `channels:history`
   - `chat:write`, `chat:write.public`
   - `reactions:read`, `reactions:write`
   - `pins:read`, `pins:write`
   - `users:read`, `users:read.email`
   - `files:read`, `files:write`
   - `search:read` (user token scope)
   - `im:write`, `im:read`
3. Install the app to your workspace
4. Copy the **Bot User OAuth Token** (`xoxb-...`)
5. Copy the **User OAuth Token** (`xoxp-...`)
6. Copy the **Signing Secret** from Basic Information page

## Connecting to AI Agents

> **Note:** Use `uvx --from workos-slack-mcp-server slack-mcp-server` in all configs below. The `--from` flag is needed because the PyPI package name (`workos-slack-mcp-server`) differs from the CLI entry point (`slack-mcp-server`). You must have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (`brew install uv` on macOS).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "slack": {
      "command": "uvx",
      "args": ["--from", "workos-slack-mcp-server", "slack-mcp-server"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_USER_TOKEN": "xoxp-your-token",
        "SLACK_SIGNING_SECRET": "your-secret"
      }
    }
  }
}
```

> **Alternative** — if you have installed via `pip install workos-slack-mcp-server` and prefer not to use uvx, use the full absolute path to the binary instead:
> ```json
> { "command": "/path/to/your/bin/slack-mcp-server" }
> ```
> Find the path with: `which slack-mcp-server`

### Cursor

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "slack": {
      "command": "uvx",
      "args": ["--from", "workos-slack-mcp-server", "slack-mcp-server"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_USER_TOKEN": "xoxp-your-token",
        "SLACK_SIGNING_SECRET": "your-secret"
      }
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Edit `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "slack": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-slack-mcp-server", "slack-mcp-server"],
      "env": {
        "SLACK_BOT_TOKEN": "${input:slackBotToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "slackBotToken",
      "type": "promptString",
      "description": "Slack Bot Token (xoxb-...)",
      "password": true
    }
  ]
}
```

### WorkOS / Custom Agents

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "slack": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-slack-mcp-server", "slack-mcp-server"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_USER_TOKEN": "${SLACK_USER_TOKEN}",
        "SLACK_SIGNING_SECRET": "${SLACK_SIGNING_SECRET}"
      }
    }
  }
}
```

## Available Tools (15)

| Tool | Description |
|------|-------------|
| `slack_send_message` | Send a message to a channel |
| `slack_read_messages` | Read recent messages from a channel |
| `slack_reply_thread` | Reply to a message thread |
| `slack_send_dm` | Send a direct message to a user |
| `slack_list_channels` | List workspace channels |
| `slack_create_channel` | Create a new channel |
| `slack_archive_channel` | Archive a channel |
| `slack_set_channel_topic` | Set channel topic |
| `slack_search_messages` | Search messages across workspace |
| `slack_add_reaction` | Add emoji reaction to a message |
| `slack_remove_reaction` | Remove emoji reaction |
| `slack_pin_message` | Pin a message in a channel |
| `slack_unpin_message` | Unpin a message |
| `slack_get_user_profile` | Get user profile information |
| `slack_upload_file` | Upload a text file to a channel |

## Development

```bash
git clone https://github.com/workos/workos-slack-mcp-server
cd workos-slack-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
SLACK_BOT_TOKEN=xoxb-... python -m slack_mcp_server
```

## Publishing

### To PyPI
```bash
pip install build twine
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*
```

### To MCP Registry
```bash
mcp-publisher login github
mcp-publisher publish
```

## License

MIT — see [LICENSE](LICENSE) for details.
