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

$3

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

$3

``bash


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
`

$3

`bash


Build image

docker build -t slack-mcp-server .

Run container

docker run -p 30001:30001 slack-mcp-server
`

$3

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

Default port: 30001

$3

All requests require a Slack Bot Token via Authorization header:

`bash
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)

$3

| 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 |

$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 |

$3

| 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 |

$3

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

$3

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

$3

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

$3

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

$3

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

Usage Examples

$3

`bash
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"
}
}
}'
`

$3

`bash
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"
}
}
}'
`

$3

`bash
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

`bash


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