slack-stdio-mcp
Provides a bridge to Slack's hosted MCP server, enabling messaging, search, history, canvas, and other workspace tools through OAuth authentication.
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-stdio-mcp Send a Slack message to #general: 'Hello from Glama!'"
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-stdio-mcp
Local MCP stdio bridge to Slack’s hosted MCP server
(https://mcp.slack.com/mcp).
Proxies the official tool catalog (slack_send_message, search, history,
canvas, …) after user OAuth (PKCE) and keeps tokens fresh. It does not
reimplement hosted Slack tools. A small local overlay adds what the hosted
server does not: download a file to disk, and list local vs remote tool names.
Approach | Typical result |
Host → HTTP | Often stuck authenticating |
Claude Code Slack plugin | Works (partner app + host OAuth) |
This bridge (stdio + local OAuth/refresh) | Works for Grok, Cursor, Open Code, Codex, Claude, … |
Agent ──stdio MCP──► slack-stdio-mcp ──Bearer──► mcp.slack.com
│
├─ valid access token → reuse
├─ expired + refresh_token → silent refresh
├─ no token → browser OAuth (PKCE)
└─ overlay: download, catalog, edit/delete, unreact, scheduledRequirements
Node.js ≥ 20 (Windows, macOS, Linux)
Default OAuth app: Claude’s partner Slack app (no app setup required)
Client ID:
1601185624273.8899143856786Redirect:
http://localhost:3118/callback
Own app is optional — see Own Slack app
Related MCP server: slack-mcp-claude-auth
Install
npx -y slack-stdio-mcpFirst run may open a browser for Slack Allow. Later runs reuse or refresh tokens under the platform credentials directory (see Auth).
Alternative | Command |
Latest git main |
|
From clone |
|
Configure a host
Prefer npx so you never hardcode a machine path. Put knobs in args
(CLI flags beat env; see Configuration).
Set startup_timeout_sec (or equivalent) ≥ 180 so the first OAuth Allow
is not killed by the host.
Grok Build (~/.grok/config.toml)
[mcp_servers.slack-stdio]
command = "npx"
args = ["-y", "slack-stdio-mcp"]
enabled = true
startup_timeout_sec = 180Own Slack app:
[mcp_servers.slack-stdio]
command = "npx"
args = [
"-y", "slack-stdio-mcp",
"--client-id", "YOUR.CLIENT.ID",
"--oauth-host", "127.0.0.1",
"--oauth-path", "/oauth/callback",
]
enabled = true
startup_timeout_sec = 180Claude Code / Cursor / similar (JSON)
{
"mcpServers": {
"slack-stdio": {
"command": "npx",
"args": ["-y", "slack-stdio-mcp"]
}
}
}Add the same optional flags as in the Grok example when using your own app.
Local clone
{
"mcpServers": {
"slack-stdio": {
"command": "node",
"args": ["/absolute/path/to/slack-stdio-mcp/src/server.mjs"]
}
}
}Auth
On start, if there is no usable token for the active client_id, the bridge
opens a browser (PKCE). Credentials are stored per client_id:
OS | Default root |
macOS / Linux |
|
Windows |
|
Path: …/by-client/<client_id>.json. Override with --creds-dir /
SLACK_STDIO_CREDS_DIR. Unix modes 0600/0700 when supported.
Action | How |
OAuth only (no MCP) |
|
Skip browser (CI) |
|
Inject token |
|
Token lifecycle
Load credentials for the current
client_idReuse access token if valid (5‑minute skew before
expires_at)Else refresh via
oauth.v2.access(grant_type=refresh_token)On refresh failure: clear that app’s file → OAuth (or fail if skip-oauth)
No session
stdio starts even when Slack has no usable token. The host handshake does not
wait on the browser. The first tool call that needs Slack returns
SLACK_REAUTH_REQUIRED and a clickable authorize URL. The agent should ask
the user to open that URL and press Allow, then retry.
Mid-session session loss
If a Slack tool fails with an auth error (isError: true or thrown error):
Silent force-refresh + reconnect + one retry
Else open browser and return
SLACK_REAUTH_REQUIREDplus the authorize URL in the tool result (clickable in chat)After Allow, the bridge reconnects in the background — retry the tool
Successful tool payloads are never scanned for auth keywords. Settled re-auth flows are not reused; the next start gets a fresh URL.
Local tool | Purpose |
| Start re-auth; optional |
| Pending re-auth + authorize URL if any |
| Write a Slack |
| JSON of local overlay names vs the current |
| Edit a message the user posted ( |
| Delete a message the user posted ( |
| Remove a reaction the user added ( |
|
|
Startup OAuth waits up to SLACK_OAUTH_TIMEOUT_MS (default 180000). On
timeout the process exits 1 (host must restart). Keep host startup timeout
above that value. The authorize URL is always printed on stderr.
Configuration
Precedence: CLI flags > environment > built-in defaults.
CLI flag | Env | Purpose |
|
| OAuth app id (default: Claude partner) |
|
| Confidential apps only |
|
| Redirect host ( |
|
| Redirect path ( |
|
| Loopback port ( |
|
| MCP endpoint |
|
| Named store: |
|
| Absolute credentials root (wins over |
|
| Never open browser |
|
| Inject Bearer (tests/CI) |
| — | Help on stderr |
Env only: SLACK_OAUTH_TIMEOUT_MS, SLACK_ALLOW_LEGACY_TOKEN=1 (flat legacy
JSON without client_id).
npx -y slack-stdio-mcp -- --profile user_cl
npx -y slack-stdio-mcp -- --client-id 123.456 --oauth-path /oauth/callback
npx -y slack-stdio-mcp -- --skip-oauth --creds-dir /tmp/empty-credsA leading -- in args (Cursor / npx) is ignored; --profile after it still applies.
Profiles: the same --profile name in every host/repo reuses
~/.slack-stdio-mcp/profiles/<name>/… (no absolute paths in config). Grok does
not inject the MCP server key into the process — put the profile string in
args yourself (convention: match your team/workspace name).
Platforms
Windows | macOS / Linux | |
Credentials |
|
|
Open browser |
|
|
File modes | omitted (profile ACL) |
|
CI: npm test on Ubuntu, Windows, macOS (Node 20 + 22). If the browser cannot
open, paste the authorize URL from stderr.
Own Slack app (optional)
Only if you are not using the default Claude partner app.
Slack app → OAuth & Permissions → Redirect URLs must match your
--oauth-*/SLACK_OAUTH_*(e.g.http://localhost:3118/callback)PKCE Opt In (recommended without
client_secret)Enable MCP under App Assistant / Agents & AI Apps
(else: App is not enabled for Slack MCP server access)User Token Scopes must match
USER_SCOPESinsrc/oauth-flow.mjs(source of truth; CI checks the README list below)
Scope | Used for |
| Search public channels |
| Search private channels |
| Search multi-person DMs |
| Search 1:1 DMs |
| Search files |
| Search users |
| Send messages |
| Public channel history |
| Private channel history |
| Multi-person DM history |
| 1:1 DM history |
| Canvases |
| Profiles |
| Reactions |
| Custom emoji |
| Files |
| Open/manage conversations |
| List/metadata |
Copy-paste (comma-separated; authorize uses space-separated scope, not
user_scope):
search:read.public,search:read.private,search:read.mpim,search:read.im,search:read.files,search:read.users,chat:write,channels:history,groups:history,mpim:history,im:history,canvases:read,canvases:write,users:read,users:read.email,reactions:write,reactions:read,emoji:read,files:read,channels:write,groups:write,im:write,mpim:write,channels:read,groups:read,mpim:readThese are user scopes (xoxp / xoxe.xoxp), not bot scopes. A subset is
fine if you only need some tools. Set SLACK_CLIENT_SECRET only if Slack
rejects public PKCE exchange.
npx -y slack-stdio-mcp -- \
--client-id your.client.id \
--oauth-host 127.0.0.1 \
--oauth-path /oauth/callbackScripts
Script | Command |
Start bridge |
|
OAuth only |
|
Tests |
|
Syntax + English gate |
|
Security
See SECURITY.md.
Never commit credentials,
.env, or token dumpsTokens act as the authorizing user — revoke the app in Slack when done
stdout = MCP JSON-RPC only; human logs go to stderr
Contributing
CONTRIBUTING.md · CHANGELOG.md · docs/ARCHITECTURE.md
License
Available Tools
8 toolsslack_stdio_catalogA
List local overlay tool names vs the current hosted mcp.slack.com catalog. Use to verify the bridge is proxying the full remote set.
Inputs: no named parameters.
slack_stdio_delete_messageB
Delete a message the user posted (chat.delete). Hosted Slack MCP cannot delete.
Inputs: channel_id (required), message_ts (required).
slack_stdio_download_fileA
Download a Slack file to disk by file_id. Hosted slack_read_file often returns metadata-only for video or large binaries; this writes the bytes to dest_dir (default: OS temp slack-stdio-mcp-downloads) and returns path, mime_type, and size. Max 50 MB. Requires files:read.
Inputs: file_id (required), dest_dir, max_bytes.
slack_stdio_reauthA
No Slack session. Ask the user to authorize Slack (open the URL and press Allow) before any Slack action, then retry. Start Slack re-authorization when the session expired. Opens a browser and returns a clickable authorize URL for the user. Optional argument wait=true blocks until Allow (or timeout). After success, retry the previous Slack tool.
Inputs: wait.
slack_stdio_remove_reactionA
Remove an emoji reaction the user added (reactions.remove). Hosted catalog has add/get only. Emoji name without colons.
Inputs: emoji (required), channel_id (required), message_ts (required).
slack_stdio_scheduled_messagesA
List or cancel scheduled messages (chat.scheduledMessages.list / chat.deleteScheduledMessage). Hosted slack_schedule_message cannot cancel. action=list (optional channel_id) or action=cancel (channel_id + scheduled_message_id).
Inputs: action (required), channel_id, scheduled_message_id.
slack_stdio_session_statusC
No Slack session. Ask the user to authorize Slack (open the URL and press Allow) before any Slack action, then retry. Report whether a Slack re-auth flow is in progress and the authorize URL if any.
Inputs: no named parameters.
slack_stdio_update_messageA
Edit a message the user posted (chat.update). Hosted Slack MCP can send but not edit. Requires channel_id, message_ts, and the new message text.
Inputs: message (required), channel_id (required), message_ts (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct capability: auth initiation, auth status, file download, catalog inspection, message update/delete, reaction removal, and scheduled message list/cancel. Even the two auth-related tools are clearly separated into start-flow versus status-report roles, so an agent should not confuse them.
All tools share the consistent slack_stdio_ prefix and use lowercase snake_case, which makes the set predictable. However, not every name follows verb_noun: reauth, catalog, session_status, and scheduled_messages are deviations, though they remain readable and still fit the overall pattern.
Eight tools is a well-scoped size for a Slack MCP bridge that supplements a hosted catalog with missing operations. Every tool addresses a concrete gap or supporting need, with no redundant clutter.
The tool surface covers the stated gaps: reauthorization, file downloads, message editing/deletion, reaction removal, and scheduled message list/cancel. It also includes status and catalog tools to make the bridge self-explanatory, so there are no obvious dead ends for the server's intended role.
Maintenance
Related MCP Connectors
Hosted Slack MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceThe most powerful MCP server for Slack Workspaces. This integration supports both Stdio and SSE transports, proxy settings and does not require any permissions or bots being created or approved by Workspace admins 😏.21,901MIT
- FlicenseNot gradedqualityDmaintenanceLocal stdio MCP proxy for the official Slack MCP endpoint, using Claude's Slack plugin for authentication to enable Slack integration via MCP without needing a custom Slack app.-
- AlicenseNot gradedqualityBmaintenanceBridge that lets stdio-only MCP clients connect to remote MCP servers with OAuth and other auth support, enabling local clients to use remote, authorized MCP servers.54MIT
- AlicenseNot gradedqualityBmaintenanceEnables posting to Slack as a bot or as a specific authorized person, and sending DMs, from any script, agent, or CI job via a local MCP server over stdio.468 npmMIT