slack-bot-mcp
Enables an AI agent to work in Slack as a bot: send DMs and channel messages, thread replies, edit or delete bot messages, search for users, list channels, read conversation history and threads, add/remove reactions, track pending questions, and wait for or check replies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@slack-bot-mcp send a DM to @sarah asking if she can review the Q3 report today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
slack-bot-mcp
An MCP server that lets an AI agent work in Slack as a bot. The agent can send DMs and channel messages, find members by email or name, read history and threads, react to messages, and wait for replies.
It is built on Chat SDK (chat + @chat-adapter/slack). By default it receives events over Socket Mode, so it needs no public URL. Set SLACK_MODE=webhook to receive events through a Request URL instead.
Quick start
SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... npx -y @liusdev/slack-bot-mcp@latest
# or
SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... pnpm dlx @liusdev/slack-bot-mcp@latestCheck the installed version with npx -y @liusdev/slack-bot-mcp@latest -v (or --version); --help lists usage. The whoami tool also reports server_version.
Claude Code
claude mcp add slack-bot \
-e SLACK_BOT_TOKEN=xoxb-... \
-e SLACK_APP_TOKEN=xapp-... \
-- npx -y @liusdev/slack-bot-mcp@latestClaude Desktop, Cursor and other MCP clients
{
"mcpServers": {
"slack-bot": {
"command": "npx",
"args": ["-y", "@liusdev/slack-bot-mcp@latest"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-...",
"SLACK_APP_TOKEN": "xapp-..."
}
}
}
}Related MCP server: Slack MCP Server
Create the Slack app
A Slack app manifest is a YAML file that describes an app's configuration. The manifest below sets up everything this server needs in one step:
a bot user that people can DM (the App Home Messages tab)
the bot token scopes the tools use
the
app_mentionandmessage.imevents, which feedget_inboxSocket Mode, so no public URL is needed
Go to api.slack.com/apps, click Create New App, choose From an app manifest, pick your workspace, and paste the manifest below.
Under Basic Information → App-Level Tokens, generate a token with the
connections:writescope. This isSLACK_APP_TOKEN(xapp-…).Under OAuth & Permissions, install the app to the workspace and copy the Bot User OAuth Token. This is
SLACK_BOT_TOKEN(xoxb-…).Invite the bot to any private channel it should read or post in:
/invite @AI Assistant.
display_information:
name: AI Assistant
features:
app_home:
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: AI Assistant
always_online: true
oauth_config:
scopes:
bot:
- app_mentions:read
- channels:history
- channels:read
- chat:write
- chat:write.public
- groups:history
- groups:read
- im:history
- im:read
- im:write
- mpim:history
- mpim:read
- reactions:read
- reactions:write
- users:read
- users:read.email
settings:
event_subscriptions:
bot_events:
- app_mention
- message.im
interactivity:
is_enabled: true
org_deploy_enabled: false
socket_mode_enabled: true
token_rotation_enabled: falseUse an existing app
To reuse an app you already created, open it at api.slack.com/apps and select App Manifest in the sidebar. Merge in the scopes, events, socket_mode_enabled and app_home settings above. Do not paste over the whole manifest: that replaces the app's current configuration and can drop scopes, events or Request URLs it already uses. Save, then click Reinstall to Workspace under OAuth & Permissions so new scopes take effect. If the app has no app-level token yet, create one as in step 2.
You can drop scopes you do not need. Tools that lack a scope return an error that names the missing scope. chat:write.public lets the bot post in public channels without being invited first.
Tools
Tool | What it does | Bot scopes |
| Bot identity, connection status, granted scopes, and the scopes each tool is missing | none |
| Find members by email, name, display name, @handle or job title |
|
| Profile of one user (ID, email or @handle) |
|
| List channels, filtered by type, name or membership |
|
| Post to a channel, a thread, or a user's DM: Markdown or plain text, an optional context line, or custom Block Kit. |
|
| Replace the content of a message the bot posted (same formatting options as |
|
| Delete a message the bot posted (bots cannot delete other people's messages) |
|
| Read recent messages in a channel or DM |
|
| Read a thread | same as above |
| Add or remove an emoji reaction |
|
| Wait briefly (default 45 s) for a reply; saves the question as pending on timeout | history scopes |
| Check all pending questions, or one conversation, once and return any answers | history scopes |
| DMs and @mentions the bot received while the server was running |
|
Wherever a tool takes a channel or user, you can pass:
a channel ID (
C…),#channel-name, or Slack markup (<#C…>)a user ID (
U…),@handle, email, or display name
For a user, the tool opens a DM with them. If a name matches several users, the tool returns the candidates so the agent can ask which one you mean.
Bot tokens cannot call Slack's search.messages API, so this server has no message search.
Message formatting
send_message has three levels of formatting:
textalone: standard Markdown (bold, lists, code, links, quotes), or plain text withformat: "plain".context: small grey details under a divider at the bottom of the message, such as the Jira ticket or comment a question refers to. Each item is{ label, value, url? }or a pre-formatted mrkdwn string:{ "target": "quy@example.com", "text": "Does `VECURA_CONTENT_BACKEND_URL` have a public staging address?", "context": [ { "label": "Jira", "value": "VEC-123", "url": "https://example.atlassian.net/browse/VEC-123" }, { "label": "Comment", "value": "#4521", "url": "https://example.atlassian.net/browse/VEC-123?focusedCommentId=4521" } ] }This renders as: the question, a divider, then Jira: VEC-123 · Comment: #4521 in small text.
blocks: any Block Kit layout (header, section fields, images and so on).textthen becomes the notification fallback, andcontextis still appended. Try layouts in the Block Kit Builder. Interactive elements such as buttons are not supported, because the server does not handle clicks. If Slack rejects the blocks, the error lists the invalid fields.
Errors
Every tool returns failures as an MCP tool error (isError: true). The text says what failed, why, and what to do. For example:
Permission denied: the Slack bot is missing the OAuth scope `reactions:write` needed to add the :eyes: reaction.
Scopes the bot currently has: chat:write,users:read.
A Slack workspace admin must add it under api.slack.com/apps → your app → OAuth & Permissions → Bot Token Scopes, then reinstall the app to the workspace.The server also explains common Slack errors: not_in_channel, channel_not_found, users_not_found, is_archived, invalid_auth, and rate limits with the retry delay. Without users:read.email, Slack silently leaves emails out of user lists. In that case, email lookups report the missing scope instead of "user not found".
Configuration
Variable | Required | Default | Description |
| yes | Bot token, | |
| socket mode | App-level token with | |
| no |
|
|
| webhook mode | Signing secret from Basic Information | |
| no |
| Port for incoming Slack events in webhook mode |
| no |
| Path for incoming Slack events in webhook mode |
| no | any | Comma-separated targets |
| no |
|
|
| no |
| Where pending questions are stored, one JSON file per workspace |
| no |
| Pending questions older than this are dropped |
Webhook mode
Set SLACK_MODE=webhook and SLACK_SIGNING_SECRET. The server then listens on SLACK_MCP_HTTP_PORT. In the app settings, turn off Socket Mode and set the Request URL under Event Subscriptions and Interactivity to https://<your-host>/slack/events.
Waiting for replies
People may answer in a minute or the next morning. Polling inside one agent turn is cheap for the server but not for the agent: every wait_for_reply call is a model turn that re-reads the whole conversation. So the server keeps waits short and remembers what it is waiting for:
The agent sends the question with
send_messageandexpect_reply: true. The server saves it as a pending question inSLACK_MCP_STATE_DIR, which outlives the MCP process and the agent session.If a quick answer is likely, the agent calls
wait_for_replyonce or twice. After two timeouts the tool tells the agent to stop and report back to the user.Later,
check_replieswith no arguments checks every pending question in one call, returns the answers, and removes answered questions from the list.
Something has to run the agent again for step 3; the server cannot wake an agent. Slack's official MCP server has no wait tool either, so agents using it re-read threads the same way. Options:
The user asks: "check Slack replies".
A loop in an open session, for example
/loop 30m check Slack replies and continuein Claude Code.A scheduled run, for example a cron job at 8:00 running
claude -p "check Slack replies and continue".
Each check is one short turn, instead of one turn every minute.
To let a single wait_for_reply call block longer, raise your client's tool timeout and pass a larger timeout_seconds (up to 300). In Claude Code, set MCP_TOOL_TIMEOUT in milliseconds, for example MCP_TOOL_TIMEOUT=320000.
Running several instances
Every tool except get_inbox calls the Slack Web API directly with the bot token. Those tools give the same results no matter how many agents run this server at once. Keep in mind:
Events are split. Slack delivers each event to only one of an app's open Socket Mode connections. Each instance's
get_inboxtherefore sees only part of the incoming messages.wait_for_replyandcheck_repliesread the Web API, so they are not affected.Connection limit. Slack allows at most 10 Socket Mode connections per app. Instances beyond that cannot open a socket, so their
get_inboxreports the connection error. Their other tools still work.Rate limits are shared. All instances spend the same token's Slack rate limits. A tool that hits a limit fails at once and says how long to wait.
Development
pnpm install
pnpm dev # rebuild on change
pnpm test
pnpm typecheck
pnpm build
npx @modelcontextprotocol/inspector node dist/index.js # try the tools interactivelyReleasing
Pushing a v* tag publishes to npm through GitHub Actions (.github/workflows/publish.yml). The workflow authenticates with npm Trusted Publishing, so the repository stores no npm token.
npm version patch # or minor / major: bumps package.json, commits, and tags
git push --follow-tags # the tag triggers the publish workflowThe workflow fails if the tag does not match the package.json version.
Available Tools
14 toolschannels_listList Slack channelsARead-only
List channels the bot can see, optionally filtered by name. Private channels and DMs appear only if the bot is a member. is_member: false means the bot must be invited before it can post there (unless it has chat:write.public).
Inputs: limit, query, types, member_only.
check_repliesCheck for Slack repliesA
Check once, without waiting, whether people answered the bot. With no arguments, checks every pending question (saved by send_message with expect_reply, or by wait_for_reply on timeout), including ones from earlier sessions; answered questions are removed from the pending list. With channel and since_ts, checks one conversation instead. Cheap to call, so use it for long waits: end your turn, then call it later from a scheduled or looped run.
Inputs: channel, dismiss, since_ts, thread_ts.
conversations_historyRead Slack channel historyARead-only
Read recent messages from a channel or DM, newest first. channel accepts a channel ID, #channel-name, or a user (ID, @handle, email) for the bot's DM with them. Use cursor from the previous response to page further back. Thread replies are not included; use conversations_replies for those.
Inputs: channel (required), limit, cursor, latest, +2 more.
conversations_repliesRead a Slack threadARead-only
Read the replies in a thread, oldest first, including the parent message. thread_ts is the ts of the parent message (or of any message in the thread).
Inputs: channel (required), thread_ts (required), limit, cursor.
delete_messageDelete a Slack messageADestructiveIdempotent
Delete a message the bot posted, identified by channel and ts (as returned by send_message). Slack only lets a bot delete its own messages. Deleting the parent of a thread leaves its replies in place. This cannot be undone, so confirm with the user unless they asked for it.
Inputs: ts (required), channel (required).
edit_messageEdit a Slack messageADestructiveIdempotent
Replace the content of a message the bot posted, identified by channel and ts (as returned by send_message). Slack only lets a bot edit its own messages. The new text, context and blocks fully replace the old content, so resend any context you want to keep.
Inputs: ts (required), text (required), channel (required), blocks, +2 more.
get_inboxGet messages sent to the botA
Return direct messages and @mentions the bot received while this MCP server was running. Only covers events delivered to this process: messages sent before it started, or delivered to another running instance of the same Slack app, are not here. To reliably fetch replies in a known channel or thread, use wait_for_reply or conversations_history.
Inputs: limit, since, channel, mark_read, +1 more.
reactions_addAdd a Slack reactionBIdempotent
Add an emoji reaction to a message as the bot.
Inputs: ts (required), emoji (required), channel (required).
reactions_removeRemove a Slack reactionADestructiveIdempotent
Remove an emoji reaction the bot previously added to a message.
Inputs: ts (required), emoji (required), channel (required).
send_messageSend a Slack messageA
Post a message as the bot to a channel, a thread, or a user's DM. target accepts a channel ID (C…), #channel-name, user ID (U…), @handle, email, or a person's name; users get a direct message. Use context to add small reference details under a divider at the bottom (Jira ticket, comment link, source, IDs). Use blocks only when you need a custom Block Kit layout (header, fields, images, etc.). Returns the message ts, which you can pass to wait_for_reply or use as thread_ts to reply in a thread.
Inputs: text (required), target (required), blocks, format, +3 more.
user_infoGet Slack user detailsBRead-only
Get profile details for one Slack user, identified by user ID (U…), email, or @handle.
Inputs: user (required).
users_searchSearch Slack usersARead-only
Find workspace members by email, real name, display name, @handle or job title. Returns user IDs to use with send_message and other tools. Exact matches come first.
Inputs: query (required), limit, include_bots.
wait_for_replyWait for a Slack replyA
Block for a short time until someone other than the bot replies in a channel, DM or thread, then return the new messages. Use it only when an answer is likely within a minute or two; every call costs a model turn. Pass since_ts = the ts of your question (from send_message). Replies both as new messages and inside the question's thread are found. On replied: false, follow the returned next_step: after a couple of timeouts, stop waiting, tell the user, and collect the answer later with check_replies. Keep timeout_seconds below your MCP client's tool-call timeout (often 60 seconds; Claude Code users can raise it with MCP_TOOL_TIMEOUT).
Inputs: channel (required), since_ts, from_user, thread_ts, +2 more.
whoamiSlack bot statusARead-only
Show the server version, which Slack bot and workspace this server is connected to, the connection mode, the OAuth scopes the bot has, and which tools are missing scopes. Call this first when a Slack action fails with a permission error.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools map to distinct resource+action pairs (send/edit/delete_message, reactions_add/remove, conversations_history/replies), and the descriptions explicitly explain boundaries. The one fuzzy cluster is read/wait behavior: check_replies, wait_for_reply, get_inbox and conversations_history all retrieve incoming messages and differ only in polling semantics and scope, which an agent must read carefully to pick correctly. user_info vs users_search is also mildly overlap-prone but clarified by the descriptions.
Conventions are mixed: verb_noun (send_message, edit_message, check_replies, get_inbox, wait_for_reply), noun_verb mirroring Slack's API (channels_list, reactions_add, reactions_remove, conversations_history, conversations_replies), a bare noun (user_info) and a bare verb-ish name (whoami). All names remain readable and most are guessable to anyone familiar with Slack's API, but there is no single predictable pattern to extrapolate from.
14 tools sit comfortably in the well-scoped 3-15 range, and each tool earns its place: identity/context, user & channel discovery, message lifecycle, reading, reactions, and reply-waiting. No obvious filler or redundant duplicate tools.
The core bot messaging lifecycle is fully covered: send, edit, delete, read history and thread replies, react/unreact, receive mentions/DMs, and wait/check for replies, plus discovery tools for users and channels. Gaps are minor-to-moderate: no file upload/download, no message search, no channel creation/invite or member listing, and edit/delete are limited to the bot's own messages, but agents can work around these for typical bot workflows.
Related MCP Connectors
Chat with your AI agents from Slack: each gets a thread in your DM, and your replies there wake it.
Enable interaction with Slack workspaces. Supports subscribing to Slack events through Resources.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
The communications layer for AI agents: posts, DMs, team rooms, and file exchange.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with Slack workspaces through OAuth authentication, supporting message reading, posting to channels and threads, and channel discovery with popularity sorting.4MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Slack workspaces through comprehensive channel management, messaging, direct messages, search functionality, and user management capabilities.303 npm3MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Slack workspaces through natural language, supporting channel management, message operations, user profiles, reactions, and threaded conversations.-
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Slack workspaces, including listing channels, posting messages, replying to threads, adding reactions, and retrieving user information.1024 npmMIT