Slack

@mindstone/mcp-server-slack

Slack workspace MCP server — channels, messages, threads, reactions, users, files, bookmarks, and scheduled messages via the Slack Web API.

*Multi-workspace Slack MCP. Host-driven OAuth, per-workspace credentials files on disk, and a security review on every release.*

Status

• Version: 0.3.7 · npm
• Auth: OAuth (host-orchestrated) (SLACK_CLIENT_SECRET)
• Tools: 39 (messages, channels, threads, users, files, pins)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

When we started building this connector, Slack had not yet released an official MCP server — that came later (announced February 2026, generally available April 2026). The community Slack MCPs available at the time each got parts of the job right, but none of them combined fast user-name lookups for small and medium workspaces, the correct mention format for modern Slack (most still used the deprecated link_names=true), support for more than one Slack workspace from the same user account, and tokens that stay on the user's own machine. Slack's official server now exists and is a fine choice for many use cases. We continue to maintain this one because the host application handles the login flow, each workspace has its own credentials file on disk under the user's control, and the connector goes through our own security review before each release.

Example interaction

"Find the most recent message from Alice in #q3-planning and react with :eyes:."

Tools the host calls:

1. lookup_user_by_email — resolves Alice's email to her Slack user ID.
2. search_slack_messages — searches #q3-planning for her most recent message, returning the channel + timestamp.
3. add_slack_reaction — adds the eyes reaction to that message.

Response (trimmed):

{

"match": { "channel": "C08X...", "ts": "1715953812.004200", "user": "U07Z...", "text": "Pushed the updated forecast to the doc, ready for review." }, "reaction": { "ok": true, "name": "eyes" } }

Requirements

• Node.js 20+
• npm
• A host application that performs the Slack OAuth flow and writes per-workspace token files to ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json. This server reads those files; it does not initiate OAuth itself.

One-click install

After clicking the button, your host will prompt you to fill: SLACK_CONFIG_PATH, SLACK_TEAM_ID, SLACK_CLIENT_SECRET, SLACK_REQUEST_TIMEOUT_MS, SLACK_MAX_RETRIES.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Slack)

{

"mcpServers": { "Slack": { "command": "npx", "args": [ "-y", "@mindstone/mcp-server-slack" ], "env": { "SLACK_CONFIG_PATH": "", "SLACK_TEAM_ID": "", "SLACK_CLIENT_SECRET": "", "SLACK_REQUEST_TIMEOUT_MS": "60000", "SLACK_MAX_RETRIES": "10" } } } }

Quick Start

Install & build

cd <path-to-repo>/connectors/slack

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-slack

Local

node dist/index.js

Configuration

This server is designed to run alongside a host application that performs the Slack OAuth flow on its own. The host writes credentials to disk; this server reads them.

Required environment variables

• SLACK_CONFIG_PATH — Path to the Slack config directory (host-managed). Contains config.json (workspace metadata) and workspaces/{teamId}.json (per-workspace tokens, mode 0600).
• SLACK_TEAM_ID — Workspace team ID (per-workspace instance).

Optional environment variables

• SLACK_CLIENT_ID — OAuth Connected App client ID. Only needed to refresh a *rotating* token. Saved non-rotating tokens authorize the Slack API directly without it. When a refresh is required but this is absent, the server fails loud with REFRESH_NO_CLIENT_CREDENTIALS and directs the host to re-authenticate.
• SLACK_CLIENT_SECRET — OAuth Connected App client secret. Same conditions as SLACK_CLIENT_ID.
• SLACK_DISABLE_REFRESH — Set to 1 to disable token refresh on this surface. The server will fail-closed with a structured auth_required response on token expiry instead of attempting an oauth.v2.access refresh. Use this on the cloud surface so desktop remains the sole refresh authority and avoids racing for single-use refresh tokens.
• SLACK_REQUEST_TIMEOUT_MS — Override the default 60s upstream timeout. Must be a positive integer ≤ 300000 (5 minutes).
• MCP_WORKSPACE_PATH — Directory that upload_slack_file reads are constrained to. Paths outside it (including symlinks pointing outside) are refused. Defaults to the system temp dir when unset.

Authentication flow

The host calls the authenticate_slack_workspace tool. The OSS server returns a structured auth_required response of the form:

{

"status": "auth_required", "user_action": { "id": "slack.connect_workspace", "label": "Connect Slack", "instruction": "Click \"Connect Slack\" in the side panel to authorise the workspace." }, "agent_action": { "instruction": "Tell the user to click the Connect Slack button in the connector settings to authorise. Then call list_slack_workspaces to verify." }, "setupToolName": "authenticate_slack_workspace" }

The host's MCP service recognises this shape and dispatches to its registered Slack OAuth orchestrator (the desktop browser flow). Once the user signs in, the host writes tokens to ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json and the server picks them up on the next call.

The OSS server never initiates OAuth itself.

Host configuration examples

This server is designed for host-orchestrated OAuth: the host writes per-workspace token files to disk and the server reads them. The examples below show the env shape — your host application is responsible for populating ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json before tool calls succeed.

Claude Desktop / Cursor

{

"mcpServers": { "Slack": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-slack"], "env": { "SLACK_CONFIG_PATH": "/absolute/path/to/slack-config", "SLACK_TEAM_ID": "T0123ABCD", "SLACK_CLIENT_ID": "your-slack-app-client-id", "SLACK_CLIENT_SECRET": "your-slack-app-client-secret" } } } }

Until the host has written ${SLACK_CONFIG_PATH}/workspaces/T0123ABCD.json for that team, every tool call returns a structured auth_required response (see the Authentication flow above).

Local development (no npm publish needed)

{

"mcpServers": { "Slack": { "command": "node", "args": [" /connectors/slack/dist/index.js"], "env": { "SLACK_CONFIG_PATH": "/absolute/path/to/slack-config", "SLACK_TEAM_ID": "T0123ABCD", "SLACK_CLIENT_ID": "your-slack-app-client-id", "SLACK_CLIENT_SECRET": "your-slack-app-client-secret" } } } }

People reads and authorization

list_slack_users, get_slack_user_profile, lookup_user_by_email, message name enrichment and the profile shown by open_slack_dm use user authorization first. If it is absent or refused for authorization, scope or token-type reasons, the read may try bot authorization once. A retry starts the read again, including pagination and username resolution. Neither authorization can supply permissions it was not granted; email lookup still needs users:read.email.

If obtaining user credentials reports TOKEN_PERSIST_FAILED, these reads try once more to obtain credentials for user authorization before starting the Slack API read. If the retry fails or finds no user credentials, the read ends without trying bot authorization. Other operational errors do not trigger authorization fallback. Writes keep their identity: opening a DM uses user authorization once, and send_myself_a_note uses only bot authorization. If Slack refuses the app's authorization, the app cannot send you a notification even while other Slack actions still work. Reconnecting may restore it.

list_slack_workspaces tests bot and user authorization independently with auth.test. connected means at least one passed; tokenHealth.botToken and tokenHealth.userToken report each result separately (valid, refused, unavailable, or missing / not_configured). Having a saved token does not establish that Slack accepts it. When no probe passes and at least one is unavailable, follow the retry/status guidance rather than reconnecting immediately. Confirmed expiry with refresh disabled still requires authentication.

The Slack API error classifier preserves the four canonical refusal strings invalid_auth, token_expired, token_revoked and account_inactive byte-for-byte as code, alongside recovery guidance and next_step. Existing API error normalizations include ratelimited → rate_limited, not_allowed_token_type → missing_scope, and users_not_found → user_not_found. Other Slack API error strings pass through unchanged as code. Refresh refusals use the provider's REFRESH_AUTH_REJECTED code with the upstream string in extra data (slack_error_code). The final tool response shape depends on the tool, including existing auth_required responses.

For the people tools and enrichment helpers named above, DM opening and send_myself_a_note, errors include token_role (user or bot) when the attempted role is known, including operational credential-acquisition errors. Structured acquisition failures keep their existing recovery shape.

Each token request reads the token file. If a permission or disk error prevents that read, bot and user token requests can use the requested role's cached credentials already held in memory, including unsaved refresh results, only when that token exists and does not need ref