Slack MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Slack workspaces through the Slack Web API.

Features

Channel Management

list_channels - List all channels in the workspace
get_channel_info - Get detailed information about a specific channel
create_channel - Create a new channel
archive_channel - Archive a channel
unarchive_channel - Unarchive a channel
set_channel_topic - Set channel topic
set_channel_purpose - Set channel purpose

User Management

list_users - List all users in the workspace
get_user_info - Get detailed information about a specific user
invite_to_channel - Invite users to a channel

Messaging

send_message - Send a message to a channel (supports Block Kit)
update_message - Update an existing message (supports Block Kit)
delete_message - Delete a message
get_channel_history - Get message history for a channel
search_messages - Search for messages across the workspace

Rich Message Formatting (Block Kit)

send_formatted_message - Send formatted messages with headers, sections, fields
send_notification_message - Send status notifications with emoji indicators
send_list_message - Send formatted lists with titles and descriptions

File Management

upload_file - Upload a file to one or more channels

Reactions

add_reaction - Add a reaction to a message
remove_reaction - Remove a reaction from a message

Workspace

get_team_info - Get information about the Slack workspace/team

Installation

Using pip (Recommended - Global Install)

For use with Claude Desktop or Claude CLI, install globally:

pip install slack-mcp-server

From source

git clone <repository-url>
cd slack-mcp-server
pip install -e .

Configuration

Secure Credential Storage (Recommended)

The Slack MCP Server uses macOS Keychain for secure credential storage. This is much safer than storing tokens in files.

Quick Setup

# Run the interactive setup
slack-mcp-setup
# or
python -m slack_mcp.setup

The setup wizard will:

Guide you through obtaining a Slack API token
Securely store credentials in your macOS Keychain
Validate your configuration

Manual Keychain Setup

from slack_mcp.credentials import CredentialManager

manager = CredentialManager()
manager.store_credential("api_token", "xoxb-your-slack-bot-token")
manager.store_credential("workspace_id", "T1234567890")  # Optional

Environment Variables (Fallback)

If you prefer environment variables or are not on macOS, create a .env file:

# Required
SLACK_API_TOKEN=xoxb-your-slack-bot-token

# Optional
SLACK_WORKSPACE_ID=your-workspace-id

⚠️ Security Warning: Environment variables and .env files are less secure than keychain storage.

Getting a Slack API Token

Go to api.slack.com/apps
Create a new app or select an existing one
Navigate to "OAuth & Permissions"
Add the required OAuth scopes (see below)
Install the app to your workspace
Copy the "Bot User OAuth Token" (starts with xoxb-)

Required OAuth Scopes

The following OAuth scopes are required for full functionality:

Core Scopes:

channels:read - View basic channel information
channels:manage - Create and manage public channels
groups:read - View private channel information
groups:write - Create and manage private channels
chat:write - Send messages
files:write - Upload files
im:read - View direct message channels
mpim:read - View group direct message channels
reactions:read - View reactions
reactions:write - Add and remove reactions
team:read - View team information
users:read - View user information

⚠️ Search Limitation:The search_messages tool uses Slack's search API which requires user tokens with the search:read scope. Since this server is designed for bot tokens (xoxb-), search functionality will not work. Consider removing this feature or switching to user token authentication if search is needed.

Usage with Claude CLI (Recommended)

After installing globally, add the server using Claude CLI. First, find your slack-mcp-server installation path:

# Find your slack-mcp-server executable path
which slack-mcp-server

Then add it with Claude CLI:

claude mcp add slack /path/to/slack-mcp-server

For example:

claude mcp add slack /usr/local/bin/slack-mcp-server

This automatically configures the server in your Claude Desktop configuration.

Usage with Claude Desktop (Manual Configuration)

Alternatively, you can manually add this to your claude_desktop_config.json:

With Keychain Storage (Recommended)

{
  "mcpServers": {
    "slack": {
      "command": "python",
      "args": ["-m", "slack_mcp"]
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "slack": {
      "command": "python",
      "args": ["-m", "slack_mcp"],
      "env": {
        "SLACK_API_TOKEN": "xoxb-your-slack-bot-token"
      }
    }
  }
}

Usage with MCP Client

from mcp import Client

# Initialize client
client = Client()

# Connect to the Slack MCP server
await client.connect("python", ["-m", "slack_mcp"])

# List available tools
tools = await client.list_tools()

# Use a tool
result = await client.call_tool("list_channels", {
    "types": "public_channel",
    "exclude_archived": True,
    "limit": 10
})

Development

Setting up the development environment

# Clone the repository
git clone <repository-url>
cd slack-mcp-server

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Set up credentials securely
slack-mcp-setup

Running tests

pytest

Code formatting

# Format with black
black slack_mcp/

# Lint with ruff
ruff check slack_mcp/

Examples

List public channels

result = await client.call_tool("list_channels", {
    "types": "public_channel",
    "exclude_archived": True,
    "limit": 20
})

Send a message

result = await client.call_tool("send_message", {
    "channel": "C1234567890",  # Channel ID
    "text": "Hello from MCP!"
})

Search for messages

result = await client.call_tool("search_messages", {
    "query": "project deadline",
    "sort": "timestamp",
    "sort_dir": "desc",
    "count": 10
})

Upload a file

result = await client.call_tool("upload_file", {
    "channels": "C1234567890,C0987654321",  # Comma-separated channel IDs
    "content": "This is the file content",
    "filename": "report.txt",
    "title": "Weekly Report",
    "initial_comment": "Here's this week's report"
})

Send a formatted message with Block Kit

result = await client.call_tool("send_formatted_message", {
    "channel": "C1234567890",
    "title": "Project Update",
    "text": "Here's the latest update on our project progress",
    "fields": "Status: In Progress, Due Date: Next Friday, Assignee: @john",
    "context": "Last updated 2 hours ago"
})

Send a notification message

result = await client.call_tool("send_notification_message", {
    "channel": "C1234567890",
    "status": "success",
    "title": "Deployment Complete",
    "description": "The application has been successfully deployed to production",
    "details": "Build #123 deployed at 14:30 UTC"
})

Send a list message

result = await client.call_tool("send_list_message", {
    "channel": "C1234567890",
    "title": "Meeting Agenda",
    "description": "Items to discuss in today's standup",
    "items": "Sprint review\nBlocker discussion\nNext week planning\nDemo preparation"
})

Send message with custom Block Kit

result = await client.call_tool("send_message", {
    "channel": "C1234567890",
    "text": "Custom formatted message",
    "blocks": json.dumps([
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Important Notice*\nThis is a custom Block Kit message"
            }
        },
        {"type": "divider"},
        {
            "type": "context",
            "elements": [
                {
                    "type": "mrkdwn",
                    "text": "Created with custom blocks"
                }
            ]
        }
    ])
})

Error Handling

The server returns JSON-formatted error messages when operations fail:

{
  "error": "Slack API error: channel_not_found"
}

Common error codes:

not_authed - Invalid or missing API token
channel_not_found - Channel doesn't exist
user_not_found - User doesn't exist
message_not_found - Message doesn't exist
no_permission - Bot lacks required permissions
rate_limited - API rate limit exceeded

Security Considerations

🔐 Keychain Storage: Use macOS Keychain for secure credential storage (recommended)
API Token: Never commit your Slack API token to version control
Permissions: Only grant the minimum required OAuth scopes
Rate Limits: The server respects Slack's rate limits (see Slack Rate Limits)
Message Content: Be mindful of sensitive information in messages and files

Credential Management Commands

# Interactive setup wizard
slack-mcp-setup

# View stored credentials
python -c "from slack_mcp.credentials import CredentialManager; m = CredentialManager(); print(m.list_stored_credentials())"

# Delete specific credential
python -c "from slack_mcp.credentials import CredentialManager; CredentialManager().delete_credential('api_token')"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

For issues and questions, please create an issue in the repository.