Slack MCP Server

A comprehensive Model Context Protocol (MCP) server providing complete Slack Web API integration with 9 tools for reading messages, managing channels, searching content, and interacting with Slack workspaces.

Features

Channel Operations (5 tools)

• List all channels you're a member of

• Get message history from channels

• Get detailed channel information

• Search messages across all channels

• Post messages to channels and threads

User Operations (4 tools)

• Get user profile information

• List all workspace users

• Get thread replies

• Get messages where you were mentioned

Related MCP server: Slack MCP Server

Prerequisites

• Python 3.12 or higher

• Slack workspace with user token access

• Slack User OAuth Token with appropriate scopes

Installation

1. Install dependencies using uv:

cd /Users/dimay/mcp/slack_mcp
uv sync

Configuration

Getting a Slack User Token

You have two options:

Option 1: Create a Slack App (Recommended)

1. Go to https://api.slack.com/apps and create a new app

2. Under OAuth & Permissions, add these User Token Scopes:

   • channels:history - View messages in public channels

   • channels:read - View basic public channel info

   • groups:history - View messages in private channels

   • groups:read - View basic private channel info

   • im:history - View direct messages

   • mpim:history - View group direct messages

   • users:read - View users in workspace

   • search:read - Search workspace content

   • chat:write - Send messages (optional, for posting)

3. Install the app to your workspace and authorize it

4. Copy the User OAuth Token (starts with xoxp-)

Option 2: Extract Token from Browser (Quick but Less Secure)

1. Open Slack in your web browser (https://app.slack.com)

2. Open Developer Tools (F12)

3. Go to Console tab

4. Run: TS.boot_data.api_token

5. Copy the token (starts with xoxc-)

Note: Browser tokens may expire and are less secure. Use OAuth method for production.

Set Environment Variables

The server supports two authentication methods:

Method 1: Browser Token + Cookie (Quick)

1. Open Slack in your browser (https://app.slack.com)

2. Open Developer Tools (F12) → Console

3. Run: TS.boot_data.api_token to get your token (starts with xoxc-)

4. Go to Application/Storage tab → Cookies → https://app.slack.com

5. Find cookie named d and copy its value (starts with xoxd-)

6. Add both to your shell profile (~/.zshrc):

export SLACK_USER_TOKEN="xoxc-your-token-here"
export SLACK_USER_COOKIE="xoxd-your-cookie-here"

Then run: source ~/.zshrc

Note: Browser tokens may expire with your browser session.

Method 2: OAuth Token (Recommended for Production)

export SLACK_USER_TOKEN="xoxp-your-oauth-token-here"

OAuth tokens (from creating a Slack App) don't require a cookie and are more reliable.

Usage

Running the MCP Server

cd /Users/dimay/mcp/slack_mcp
uv run slack_mcp_server.py

Configuring with Claude Code

Add to your Claude Code MCP settings:

For Browser Token (xoxc-):

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": ["run", "slack_mcp_server.py"],
      "cwd": "/Users/dimay/mcp/slack_mcp",
      "env": {
        "SLACK_USER_TOKEN": "xoxc-your-token-here",
        "SLACK_USER_COOKIE": "xoxd-your-cookie-here"
      }
    }
  }
}

For OAuth Token (xoxp-):

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": ["run", "slack_mcp_server.py"],
      "cwd": "/Users/dimay/mcp/slack_mcp",
      "env": {
        "SLACK_USER_TOKEN": "xoxp-your-token-here"
      }
    }
  }
}

Alternatively, if you've set the environment variables in your shell profile, you can omit the env section entirely.

Available Tools (9 Total)

Channel Operations

slack_list_channels

List all channels you're a member of.

Parameters:

• types (optional): Comma-separated types (default: "public_channel,private_channel")

  • Options: public_channel, private_channel, mpim, im

• exclude_archived (optional): Exclude archived channels (default: true)

• limit (optional): Maximum channels to return (default: 1000)

Returns: List of channels with ID, name, member count, topic, and purpose

Example:

{
  "types": "public_channel,private_channel",
  "exclude_archived": true
}

slack_get_channel_history

Get messages from a specific channel.

Parameters:

• channel_id (required): Channel ID (e.g., "C1234567890")

• limit (optional): Number of messages (max 1000, default: 100)

• oldest (optional): Unix timestamp - only messages after this time

• latest (optional): Unix timestamp - only messages before this time

Returns: List of messages with user, text, and timestamp

Example:

{
  "channel_id": "C1234567890",
  "limit": 50
}

slack_get_channel_info

Get detailed information about a channel.

Parameters:

• channel_id (required): Channel ID

Returns: Channel details including name, topic, purpose, creator, member count

slack_search_messages

Search for messages across all channels.

Parameters:

• query (required): Search query (supports Slack search syntax)

• count (optional): Number of results (max 100, default: 20)

• sort (optional): Sort by "timestamp" or "score" (default: "timestamp")

• sort_dir (optional): "asc" or "desc" (default: "desc")

Returns: Matching messages with channel context and permalinks

Search Examples:

• from:@username - Messages from specific user

• in:#channel-name - Messages in specific channel

• during:2024-01 - Messages during January 2024

• has:link - Messages containing links

• "exact phrase" - Exact phrase match

slack_post_message

Post a message to a channel.

Parameters:

• channel_id (required): Channel ID

• text (required): Message text (supports Slack markdown)

• thread_ts (optional): Thread timestamp to reply to

Returns: Posted message confirmation with timestamp

Note: Requires chat:write scope

User Operations

slack_get_user_info

Get information about a specific user.

Parameters:

• user_id (required): User ID (e.g., "U1234567890")

Returns: User profile with name, email, title, status, and admin flags

slack_list_users

List all users in the workspace.

Parameters:

• limit (optional): Maximum users to return (default: 1000)

Returns: List of active users with profile information

slack_get_thread_replies

Get all replies in a thread.

Parameters:

• channel_id (required): Channel ID

• thread_ts (required): Thread timestamp (parent message ts)

• limit (optional): Maximum replies (default: 100)

Returns: All messages in the thread

slack_get_mentions

Get messages where you were mentioned.

Parameters:

• hours (optional): Look back this many hours (default: 24)

• count (optional): Number of results to return (max 100, default: 20)

Returns: Messages mentioning you with channel context and permalinks

Example:

{
  "hours": 24,
  "count": 10
}

Use Cases:

• "What did I miss while I was away?"

• "Where was I mentioned today?"

• "Show me all mentions from the last week"

Common Workflows

Reading Channel Messages

1. List your channels:
   Tool: slack_list_channels

2. Find the channel you want (note the channel ID)

3. Get messages from that channel:
   Tool: slack_get_channel_history
   channel_id: "C1234567890"
   limit: 100

Searching for Information

1. Search across all channels:
   Tool: slack_search_messages
   query: "bug report from:@john"
   count: 20

2. Get user details if needed:
   Tool: slack_get_user_info
   user_id: "U1234567890"

Reading Thread Conversations

1. Get channel history to find a thread:
   Tool: slack_get_channel_history
   channel_id: "C1234567890"

2. Get all replies in a specific thread:
   Tool: slack_get_thread_replies
   channel_id: "C1234567890"
   thread_ts: "1234567890.123456"

Posting Messages

1. List channels to find where to post:
   Tool: slack_list_channels

2. Post a message:
   Tool: slack_post_message
   channel_id: "C1234567890"
   text: "Hello from MCP!"

3. Reply to a thread:
   Tool: slack_post_message
   channel_id: "C1234567890"
   text: "Reply message"
   thread_ts: "1234567890.123456"

Catching Up on Mentions

1. Check mentions from the last 24 hours:
   Tool: slack_get_mentions
   hours: 24
   count: 20

2. Check mentions from the last week:
   Tool: slack_get_mentions
   hours: 168
   count: 50

Understanding Slack IDs

Slack uses unique IDs for different objects:

• Channel IDs: Start with C (e.g., C1234567890)

• User IDs: Start with U (e.g., U1234567890)

• Direct Message IDs: Start with D (e.g., D1234567890)

• Group DM IDs: Start with G (e.g., G1234567890)

• Message Timestamps: Unix timestamps (e.g., 1234567890.123456)

Slack Search Syntax

The slack_search_messages tool supports advanced search operators:

• from:@username - Messages from specific user

• in:#channel - Messages in specific channel

• to:@username - Direct messages to user

• on:YYYY-MM-DD - Messages on specific date

• before:YYYY-MM-DD - Messages before date

• after:YYYY-MM-DD - Messages after date

• during:YYYY-MM - Messages during month

• has:link - Messages with links

• has:pin - Pinned messages

• has::emoji: - Messages with specific reaction

• "exact phrase" - Exact phrase match

• -word - Exclude messages with word

Troubleshooting

Authentication Issues

Error: "SLACK_USER_TOKEN environment variable not set"

• Set the environment variable: export SLACK_USER_TOKEN="xoxp-..."

• Check your shell profile if it's not persisting

Error: "invalid_auth"

• Your token may be expired or invalid

• Create a new token using the OAuth method

• Ensure you copied the full token (they're quite long)

Permission Errors

Error: "missing_scope"

• Your token doesn't have required permissions

• Add the necessary scopes to your Slack App

• Reinstall the app to your workspace to apply new scopes

Error: "channel_not_found"

• The channel ID is incorrect

• You're not a member of that channel

• Use slack_list_channels to find valid channel IDs

Rate Limiting

Slack has rate limits:

• Tier 3 methods (reading): 50+ requests per minute

• Tier 2 methods (posting): 20+ requests per minute

If you hit rate limits, wait a minute before retrying.

Development

Project Structure

slack_mcp/
├── slack_mcp_server.py  # Main MCP server (8 tools)
├── pyproject.toml       # Project dependencies
├── .gitignore          # Git ignore rules
├── .python-version     # Python version specification
└── README.md           # This file

Architecture

The server is organized into sections:

• Shared Utilities: Slack client, error handling, message formatting

• Channel Operations: Channel listing, history, search, posting

• User Operations: User info, workspace members, threads

• MCP Handlers: Tool registration and execution

Error Handling

All tools provide consistent error responses with:

• Clear error messages from Slack API

• Detailed error information

• Helpful suggestions for resolution

Security Best Practices

1. Never commit tokens - Use environment variables

2. Use OAuth tokens - More secure than browser tokens

3. Minimum scopes - Only request permissions you need

4. Rotate tokens - Regenerate tokens periodically

5. Monitor usage - Check Slack App dashboard for suspicious activity

Version History

v0.1.0 (Current)

• Initial release with 8 tools

• Channel operations (list, history, info, search, post)

• User operations (info, list, threads)

• Complete Slack Web API integration

• Support for public/private channels and DMs

License

MIT

Related Resources

• Slack Web API Documentation

• Slack Search Syntax

• MCP Documentation