Slack Webhook MCP Server
A Model Context Protocol (MCP) server for posting messages to Slack via webhooks or bot tokens.
Features
- Two modes of operation: Webhooks or Bot API
- Post messages to Slack channels
- Support for channel overrides
- Configurable bot username and emoji
- Slack-specific mention support (
<!channel>,<!here>,<@USERID>) - Comprehensive error handling and validation
Installation
bun install
Setup
Option 1: Webhook Mode (Simple)
-
Create a Slack App and Webhook:
- Go to Slack API Apps
- Create a new app or select an existing one
- Navigate to "Incoming Webhooks"
- Enable incoming webhooks
- Add a new webhook to your workspace
- Copy the webhook URL (format:
https://hooks.slack.com/services/T.../B.../...)
-
Configure MCP Client:
{
"mcpServers": {
"slack-webhook": {
"command": "bun",
"args": [
"run",
"src/index.ts",
"--webhook-url",
"https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
"--channel",
"#general"
],
"cwd": "/path/to/slack-webhook-mcp-server"
}
}
}
Option 2: Bot Token Mode (Advanced)
-
Create a Slack App with Bot Token:
- Go to Slack API Apps
- Create a new app or select an existing one
- Go to "OAuth & Permissions"
- Add bot token scopes:
chat:write,chat:write.public - Install app to workspace
- Copy the "Bot User OAuth Token" (starts with
xoxb-)
-
Get Channel IDs:
- Right-click on channel in Slack → "View channel details" → Copy channel ID
- Or use Slack API to list channels
-
Configure MCP Client:
{
"mcpServers": {
"slack-bot": {
"command": "bun",
"args": [
"run",
"src/index.ts",
"--bot-token",
"xoxb-YOUR-BOT-TOKEN",
"--channel",
"CXXXXXXXXXX",
"--username",
"MCP Bot"
],
"cwd": "/path/to/slack-webhook-mcp-server"
}
}
}
Usage
Command Line Arguments
Webhook Mode:
--webhook-url <url>- Slack webhook URL (required)--channel <channel>- Default channel name (optional, e.g., "#general")
Bot Mode:
--bot-token <token>- Slack bot token (required, starts withxoxb-)--channel <channel>- Default channel ID (required, e.g., "CXXXXXXXXXX")
Common Options:
--username <username>- Default bot username (optional)--icon-emoji <emoji>- Default bot emoji (optional, e.g., ":robot_face:")--help- Show help message
Examples
Webhook Mode:
bun run src/index.ts \
--webhook-url "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" \
--channel "#general" \
--username "Assistant"
Bot Mode:
bun run src/index.ts \
--bot-token "xoxb-YOUR-BOT-TOKEN" \
--channel "CXXXXXXXXXX" \
--username "Assistant"
Available Tools
post_slack_message
Post a message to your configured Slack integration.
Parameters:
message(required): The message content to send (max 4000 characters)channel(optional): Channel to post to (overrides default)- Webhook mode: Channel name (e.g., "#random")
- Bot mode: Channel ID (e.g., "CXXXXXXXXXX")
username(optional): Override the default username for this messageicon_emoji(optional): Override the default emoji for this message
Example usage in MCP client:
Please post "Hello from MCP!" to the general channel
Mode Comparison
| Feature | Webhook Mode | Bot Mode |
|---|---|---|
| Setup | Simple | Requires OAuth setup |
| Channel Reference | Names (#general) | IDs (CXXXXXXXXXX) |
| Permissions | Limited to webhook channel | Configurable scopes |
| Rate Limits | Higher | Standard API limits |
| Features | Basic messaging | Full API access |
| Authentication | URL-based | Token-based |
Slack-Specific Features
Mentions
- User mention:
<@U1234567890> - Channel notification:
<!channel> - Here notification:
<!here>
Channel References
- Webhook mode: Use
#channel-nameformat - Bot mode: Use channel IDs like
CXXXXXXXXXX
Development
Scripts
bun run start- Start the serverbun run dev- Start with file watchingbun run build- Build for production
Project Structure
slack-webhook-mcp-server/
├── package.json # Dependencies and scripts
├── src/
│ └── index.ts # Main server implementation
├── types/
│ └── slack.ts # TypeScript types and schemas
└── README.md # This file
Error Handling
The server includes comprehensive error handling for:
- Invalid webhook URLs and bot tokens
- Network connectivity issues
- Slack API errors (different handling for webhook vs bot)
- Message length validation (4000 char limit)
- Channel ID validation (bot mode)
- Malformed requests
License
MIT