mcp-slack by dennisonbertram - MCP Server

MCP Slack Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Slack workspaces through a standardized interface.

Features

🔧 Core Tools (8)

slack_list_channels - List public channels with pagination support
slack_post_message - Post messages to channels
slack_reply_to_thread - Reply to message threads
slack_add_reaction - Add emoji reactions to messages
slack_get_channel_history - Retrieve channel messages (with automatic token limiting)
slack_get_thread_replies - Get all replies in a thread
slack_get_users - List workspace users with pagination
slack_get_user_profile - Get detailed user profile information

✨ Enhanced Tools (6 New)

slack_search_channels - Search channels by name/topic/purpose (fuzzy matching)
slack_lookup_user - Find a user by username/email/display name
slack_search_users - Search all users matching a query
slack_message_user - Send DMs easily (no channel ID needed!)
slack_get_channel_by_reference - Parse Slack URLs or find by name
slack_search_messages - Search messages with smart pagination

📋 Resources

Slack Communication Guidelines - Best practices for concise, terse Slack messaging

💬 Prompts

slack_message - Generate concise Slack messages
slack_dm - Compose brief, professional DMs

🚀 Key Improvements

Easy DMs - Message users by username or email, no complex channel IDs
Channel Search - Find channels quickly with fuzzy search
URL Parsing - Automatically extract channel IDs from Slack URLs
Token Safety - Automatic response limiting to prevent MCP token overflow
Terse Messaging - Built-in guidelines for Slack-appropriate brevity

Prerequisites

Node.js 18+ and npm
Slack workspace with admin access
Slack Bot User OAuth Token
MCP-compatible client (Claude Desktop, VS Code, etc.)

Installation

Clone the repository:

git clone https://github.com/your-org/mcp-slack.git
cd mcp-slack

Install dependencies:

npm install

Build the project:

npm run build

Set up environment variables:

cp .env.example .env
# Edit .env with your Slack credentials

Configuration

Getting Slack Credentials

Create a Slack App:
- Go to api.slack.com/apps
- Click "Create New App" → "From scratch"
- Name your app and select your workspace
Configure Bot Token Scopes: Navigate to "OAuth & Permissions" and add these Bot Token Scopes:
- channels:read - View public channels
- chat:write - Post messages
- reactions:write - Add reactions
- users:read - View users
- users.profile:read - View user profiles
- channels:history - View channel messages
- groups:history - View private channel messages (optional)
- im:write - Send direct messages (for DM functionality)
- im:history - View direct message history
- search:read - Search messages (optional, for message search)
Install App to Workspace:
- Click "Install to Workspace"
- Authorize the permissions
- Copy the "Bot User OAuth Token" (starts with xoxb-)
Get Team ID:
- Open Slack in browser
- The URL contains your team ID: https://app.slack.com/client/T0123456789/...
- Or use team.info API test

Environment Variables

Create a .env file with:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_TEAM_ID=T0123456789
SLACK_CHANNEL_IDS=C01234567,C89012345  # Optional: limit to specific channels
LOG_LEVEL=info                          # Optional: debug, info, warn, error

Usage

With Claude Desktop

Add to Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/path/to/mcp-slack/dist/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T0123456789"
      }
    }
  }
}

Restart Claude Desktop
Use natural language to interact:

Basic Operations:

"List all public Slack channels"
"Post 'Hello team!' to #general"
"Show recent messages in #engineering"

Enhanced Features:

"Search for channels about frontend"
"Send a DM to dennison saying 'Meeting at 3pm'"
"Find the user with email john@company.com"
"Get info about this channel: https://workspace.slack.com/archives/C08B2SAPZ3K"
"Search for messages mentioning 'deployment' in the last week"

With MCP CLI

# Direct execution
SLACK_BOT_TOKEN=xoxb-your-token SLACK_TEAM_ID=T0123456789 \
  npx @modelcontextprotocol/cli serve ./dist/index.js

# Or using npm script
npm run serve

Programmatic Usage

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["./dist/index.js"],
  env: {
    SLACK_BOT_TOKEN: process.env.SLACK_BOT_TOKEN,
    SLACK_TEAM_ID: process.env.SLACK_TEAM_ID
  }
});

const client = new Client({ name: "slack-client", version: "1.0.0" });
await client.connect(transport);

// List channels
const result = await client.callTool({
  name: "slack_list_channels",
  arguments: { limit: 10 }
});

Development

Project Structure

mcp-slack/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── server.ts          # MCP server setup
│   ├── slack-client.ts    # Slack API wrapper
│   ├── tools/             # Tool implementations
│   │   ├── channels.ts
│   │   ├── messages.ts
│   │   └── users.ts
│   ├── types/             # TypeScript definitions
│   └── utils/             # Helper functions
├── test/                  # Test files
├── docs/                  # Documentation
└── dist/                  # Compiled output

Available Scripts

npm run build          # Compile TypeScript
npm run watch         # Watch mode for development
npm run serve         # Run the MCP server
npm test             # Run tests
npm run lint         # Lint code
npm run format       # Format with Prettier

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- slack-client.test.ts

API Rate Limits

The server respects Slack's rate limits:

Tier 1: 1+ requests/minute
Tier 2: 20+ requests/minute (most methods)
Tier 3: 50+ requests/minute (list methods)
Tier 4: 100+ requests/minute

The server automatically handles rate limiting with exponential backoff.

Troubleshooting

Common Issues

"channel_not_found" error:
- Ensure bot is invited to the channel
- Check channel ID is correct (starts with C)
"not_authed" or "invalid_auth":
- Verify SLACK_BOT_TOKEN is correct
- Check token starts with xoxb-
- Ensure app is installed to workspace
Rate limiting errors:
- Server auto-retries with backoff
- Reduce request frequency if persistent
- Check Slack plan limits

Debug Mode

Enable detailed logging:

LOG_LEVEL=debug npm run serve

Security Considerations

Never commit .env files or tokens to version control
Store tokens securely (use environment variables or secrets management)
Limit bot permissions to minimum required
Use SLACK_CHANNEL_IDS to restrict channel access
Regularly rotate tokens
Monitor bot activity in Slack admin panel

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

See for detailed guidelines.

License

MIT - See file

Support

Acknowledgments

Built with Model Context Protocol SDK
Powered by Slack Web API
Inspired by the MCP community

Current Version: 0.6.2 MCP SDK Version: 1.0.1 Protocol Version: 2025-06-18