Slack MCP Server

A stateless Model Context Protocol (MCP) server for Slack workspace integration with comprehensive messaging, user management, and workspace analytics capabilities.

Features

• 24 Comprehensive Tools: Full Slack API coverage for messaging, users, channels, files, and more
• Enhanced Descriptions: LLM-friendly parameter descriptions for better tool usage
• Caching System: Intelligent caching with 24h users / 6h channels TTL for performance
• Name Resolution: Automatic resolution of #channel, @user to IDs
• Time-based Limits: Support for "1d", "1w", "30d" format in message queries
• Stateless Architecture: Each request is independent with no session management
• Bearer Token Auth: Per-request authentication via Authorization header

Quick Start

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Slack Bot Token with appropriate scopes

Installation

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Start production server
pnpm start

# Start development server with hot reload
pnpm run dev

# Start with debug logging
pnpm run dev:debug

Docker

# Build image
docker build -t slack-mcp-server .

# Run container
docker run -p 30001:30001 slack-mcp-server

Endpoints

• POST /mcp - Main MCP endpoint for tool execution
• GET /health - Health check endpoint

Default port: 30001

Authentication

All requests require a Slack Bot Token via Authorization header:

Authorization: Bearer xoxb-your-slack-bot-token

Create a Slack App and get a Bot User OAuth Token with these scopes:

• channels:read, channels:history - Public channels
• groups:read, groups:history - Private channels
• im:read, im:history - Direct messages
• mpim:read, mpim:history - Group DMs
• users:read - User information
• chat:write - Send messages
• reactions:write - Add reactions
• files:read - List files
• team:read - Workspace info

Tools (24 total)

Conversation Tools (5)

| Tool | Description | |------|-------------| | conversations_history | Get messages from a channel or DM with user details | | conversations_replies | Get thread replies by channel and thread_ts | | conversations_add_message | Send a message (supports threading) | | conversations_search_messages | Search with filters (URL lookup, date, user) | | bulk_conversations_history | Fetch multiple channels efficiently |

User Tools (3)

| Tool | Description | |------|-------------| | users_list | List users (filter by active/deleted/admins) | | user_info | Get detailed info for one or more users | | user_presence | Get online/away status |

Channel Tools (6)

| Tool | Description | |------|-------------| | channel_info | Get channel details (cache-first) | | channel_members | List members with details | | channels_list | List by type (public, private, im, mpim) | | channels_detailed | Efficient bulk channel listing | | set_channel_topic | Update channel topic | | set_channel_purpose | Update channel purpose |

Message Tools (2)

| Tool | Description | |------|-------------| | message_permalink | Get permanent link to message | | add_reaction | Add emoji reaction |

File Tools (1)

| Tool | Description | |------|-------------| | files_list | List files (filter by channel/user/type) |

Workspace Tools (1)

| Tool | Description | |------|-------------| | workspace_info | Get team name, domain, enterprise info |

Cache Tools (3)

| Tool | Description | |------|-------------| | initialize_cache | Pre-populate users and channels cache | | cache_info | Get cache file locations and freshness | | clear_cache | Force cache refresh |

System Tools (2)

| Tool | Description | |------|-------------| | check_permissions | Test token scopes | | analytics_summary | Workspace stats from cache |

Usage Examples

Get channel messages

curl -X POST http://localhost:30001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xoxb-your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "conversations_history",
      "arguments": {
        "channel_id": "#general",
        "limit": "1d"
      }
    }
  }'

Search messages

curl -X POST http://localhost:30001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xoxb-your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "conversations_search_messages",
      "arguments": {
        "search_query": "deployment",
        "filter_in_channel": "#engineering",
        "filter_date_after": "2024-01-01"
      }
    }
  }'

Send a message

curl -X POST http://localhost:30001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xoxb-your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "conversations_add_message",
      "arguments": {
        "channel_id": "#general",
        "payload": "Hello from MCP! *bold* and _italic_"
      }
    }
  }'

Caching

The server uses file-based caching for performance:

• Users cache: ~/slack-cache/users_cache.json (24h TTL)
• Channels cache: ~/slack-cache/channels_cache_v2.json (6h TTL)

Override paths via environment variables:

• SLACK_MCP_USERS_CACHE
• SLACK_MCP_CHANNELS_CACHE

Use initialize_cache at the start of sessions for best performance.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 30001 | | DEBUG | Enable debug output | false | | SLACK_MCP_USERS_CACHE | Custom users cache path | ~/slack-cache/users_cache.json | | SLACK_MCP_CHANNELS_CACHE | Custom channels cache path | ~/slack-cache/channels_cache_v2.json |

Development

# Run with hot reload
pnpm run dev

# Run with debug logging
DEBUG=true pnpm run dev

# Type check
pnpm run build

License

PROPRIETARY - BlueNexus AI