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:

1. Guide you through obtaining a Slack API token
2. Securely store credentials in your macOS Keychain
3. 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

1. Go to api.slack.com/apps
2. Create a new app or select an existing one
3. Navigate to "OAuth & Permissions"
4. Add the required OAuth scopes (see below)
5. Install the app to your workspace
6. 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.