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

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