Metadata-Version: 2.4
Name: workos-slack-mcp-server
Version: 1.0.0
Summary: MCP server for Slack workspace operations — send messages, manage channels, search conversations, and more.
Author: WorkOS Contributors
License: MIT
Project-URL: Homepage, https://github.com/workos/workos-slack-mcp-server
Project-URL: Repository, https://github.com/workos/workos-slack-mcp-server
Project-URL: Issues, https://github.com/workos/workos-slack-mcp-server/issues
Keywords: mcp,slack,model-context-protocol,ai-tools,chatbot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# 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

```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

# Run the server
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

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "slack": {
      "command": "slack-mcp-server",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_USER_TOKEN": "xoxp-your-token",
        "SLACK_SIGNING_SECRET": "your-secret"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "slack": {
      "command": "slack-mcp-server",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token"
      }
    }
  }
}
```

### WorkOS / Custom Agents

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "slack": {
      "transport": "stdio",
      "command": "python",
      "args": ["-m", "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-test python -m slack_mcp_server
```

## Publishing

### To PyPI
```bash
pip install build twine
python -m build
twine upload dist/*
```

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

## License

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