Slack MCP Server

Slack MCP Server

Give your AI agent full Slack access — and structured workflow output the AI can actually use. No app registration, no admin approval, no OAuth. One command, 21 tools, works with any MCP client.

npx -y @jtalk22/slack-mcp --setup

▶ Watch the demo — 7 scenarios, from 47 unreads to inbox zero, without opening Slack.

Ask your AI to catch you up on #engineering from the last 24 hours. Search for that deployment thread from last week. Find the printer admin PIN nobody can remember. Send a reply. All from your editor.

Interactive demo · Latest release

Why This Exists

Slack's official MCP server is OAuth-first and can require a registered app, admin approval, or client compatibility workarounds. See the tracked Claude Code/GitHub Copilot compatibility discussion. Screenshotting messages is not a workflow.

This server uses your browser's session tokens instead. If you can see it in Slack, your AI agent can see it too. No app install, no scopes, no admin.

Session-token transport: No bot user appears in the workspace admin panel, no app install shows up, no audit trail entry is created. Your AI agent operates with the same workspace footprint as your browser tab — nothing more, nothing less.

Workflow Primitives

Introduced in 4.2. Save a workflow profile that binds a workflow_kind to channels + priority people + retention + cadence. Stored locally at ~/.slack-mcp-workflows.json. The hosted brain at mcp.revasserlabs.com reads these profiles and returns structured JSON per workflow_kind — downstream automation (Linear, Notion, status dashboards) consumes the JSON directly.

Six prebuilt templates ship with the package:

npx -y @jtalk22/slack-mcp --apply-template oncall-handoff --channels C012345,C067890

Available templates: oncall-handoff, support-triage, exec-monday, sprint-tracker, customer-feedback, incident-room. The structural primitives (slack_workflow_save, slack_workflows) are free forever in OSS; the hosted brain is $0 to start (no card) and $19/mo Pro for unlimited AI tools.

Quick Start per Client

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

{
  "mcpServers": {
    "slack": { "command": "npx", "args": ["-y", "@jtalk22/slack-mcp"] }
  }
}

[mcp_servers.slack]
command = "npx"
args = ["-y", "@jtalk22/slack-mcp"]

Tools

21 tools total: 12 read-only Slack, 4 write-path Slack, 2 workflow profile primitives (1 local-write, 1 read-only), 3 hosted stubs. All carry MCP safety annotations.

* slack_refresh_tokens modifies local token file only.

† Hosted stubs return a structured upgrade payload (signup_url, free_tier_quota, pro_value_prop) — no Slack write occurs from OSS. Activate the brain at mcp.revasserlabs.com (free tier, no card).

‡ Also accepts include_rich_message_fields to return attachments, blocks, files, reactions, and metadata — see Rich Message Fields.

Install

Node.js 20+

npx -y @jtalk22/slack-mcp --setup

The setup wizard handles token extraction and validation.

After setup, have your client run slack_health_check — a workspace name in the response confirms you are connected.

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"]
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"],
      "env": {
        "SLACK_TOKEN": "xoxc-your-token",
        "SLACK_COOKIE": "xoxd-your-cookie"
      }
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jtalk22/slack-mcp"]
    }
  }
}

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@jtalk22/slack-mcp"],
    "env": {
      "SLACK_TOKEN": "xoxc-your-token",
      "SLACK_COOKIE": "xoxd-your-cookie"
    }
  }
}

docker pull ghcr.io/jtalk22/slack-mcp-server:latest

{
  "mcpServers": {
    "slack": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-v", "~/.slack-mcp-tokens.json:/root/.slack-mcp-tokens.json",
               "ghcr.io/jtalk22/slack-mcp-server"]
    }
  }
}

Restart your client after configuration. Full setup: docs/SETUP.md

How It Works

Session tokens (xoxc- + xoxd-) from your browser. If you can see it in Slack, this server can see it too.

Token persistence — four-layer fallback:

1. Environment variables (SLACK_TOKEN, SLACK_COOKIE)
2. Token file (~/.slack-mcp-tokens.json, chmod 600)
3. macOS Keychain (encrypted)
4. Chrome auto-extraction (macOS)

Tokens expire. The server notices before you do — proactive health monitoring, automatic refresh on macOS, warnings when tokens age out. File writes are atomic (temp file → chmod → rename) to prevent corruption. Concurrent refresh attempts are mutex-locked.

Token expired? / OAuth Lifeboat

Session tokens (xoxc- + xoxd-) are extracted from your browser, and Slack rotates them roughly every 1-2 weeks. When they die, every tool call fails to authenticate. Instead of surfacing a raw Slack error, this server detects token death — invalid_auth, not_authed, token_expired, token_revoked, account_inactive, or an HTTP 401 — and returns a recovery message at the moment of pain.

Self-fix — re-extract fresh tokens:

npx -y @jtalk22/slack-mcp --setup

On macOS with a logged-in Slack tab open in Chrome, you can instead call the slack_refresh_tokens tool (or run npm run tokens:auto). To avoid silent expiration during long idle windows, set up the optional token-refresh LaunchAgent.

Permanent fix — no rotation: the hosted version uses OAuth, which does not rotate every 1-2 weeks. Free tier available, no card.

The recovery message appears at most once per process per hour; repeat failures inside that window get a one-line reminder so agents in retry loops don't spam. Set SLACK_MCP_NO_UPSELL=1 to drop the hosted-option line while keeping the self-fix guidance.

Rich Message Fields

Added in 4.4.0. The four read tools marked ‡ above accept include_rich_message_fields: true, which surfaces the parts of a message that live outside text — attachments, blocks, files, reactions, metadata, plus subtype/bot_id/app_id (automated/bot/app markers) and team (workspace id).

An attachment-only alert reads as empty without the flag:

{ "ts": "1767368030.607599", "user": "incident-bot", "text": "" }

With include_rich_message_fields: true, the content is surfaced:

{
  "ts": "1767368030.607599",
  "user": "incident-bot",
  "text": "",
  "subtype": "bot_message",
  "bot_id": "B012345",
  "attachments": [{ "title": "PagerDuty", "text": "P1 — API latency > 2s" }]
}

Output shape only — no extra permissions. blocks can be large, so it is opt-in per call to keep client context lean. For the full developer payload inside metadata, also set include_all_metadata: true (an independent Slack flag).

slack_search_messages accepts the flag, but Slack's search API does not return rich fields on matches — read full content with slack_conversations_history or slack_get_thread on the match's channel and timestamp.

Patch by @rvandam (#143).

Hosted HTTP Mode

For remote MCP endpoints (Cloudflare Worker, VPS, etc.):

SLACK_TOKEN=xoxc-... \
SLACK_COOKIE=xoxd-... \
SLACK_MCP_HTTP_AUTH_TOKEN=change-this \
SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai \
node src/server-http.js

Details: docs/DEPLOYMENT-MODES.md

Troubleshooting

Tokens expired: Run npx -y @jtalk22/slack-mcp --setup or use slack_refresh_tokens (macOS). To prevent silent expiration during long Claude-idle windows, set up the optional token-refresh LaunchAgent.

DMs not showing: Use slack_list_conversations with discover_dms=true.

Client not seeing tools: Check JSON syntax in config, restart client fully.

More: docs/TROUBLESHOOTING.md

Docs

• Setup Guide
• API Reference
• Roadmap
• Architecture
• Deployment Modes
• Use Case Recipes
• Troubleshooting
• Compatibility

Security

• Token files: chmod 600 (owner-only)
• macOS Keychain encrypted backup
• Web server binds to localhost only
• API keys: crypto.randomBytes
• See SECURITY.md

Contributing

PRs welcome. Run node --check on modified files before submitting.

License

MIT — See LICENSE

Disclaimer

Not affiliated with Slack Technologies, Inc. Uses browser session credentials — check your workspace's acceptable use policy.

Hosted version live at mcp.revasserlabs.com: Free tier (no card — 2,000 requests/mo + 25 AI tool calls/mo), $19/mo Pro (unlimited, permanent OAuth), $49/mo Team flat, and Safeguard $199/mo (waitlist). Hosted owns the AI brain (smart_search, catch_me_up, triage), permanent OAuth (no 2-week token rotation), and shared workflow profiles; the scheduled morning catch-up DM at 8am workspace time is a Safeguard feature (in development). The OSS package owns local stdio + the 16 Slack tools (12 read, 4 write) + workflow profile primitives (slack_workflow_save, slack_workflows). The 3 paid stubs (slack_smart_search, slack_catch_me_up, slack_triage) appear in OSS as discoverable upgrade prompts.